module Bakelite::Docs::D_CONTAINERS::BINARY_CONTAINERS

Overview

Binary Containers and CLI Toolchain

Bakelite includes a dedicated binary container format (.bkl) that can be stored as standalone packages or appended directly to compiled executables (ELF, Mach-O, PE). A 32-byte trailer at the end of the file allows the runtime to discover and mount the embedded volumes with zero overhead.

Executive Summary & Key Topics

Topic	Method / Anchor	Description
Binary Layout Specification	`.topic_01_container_layout`	Organization of raw chunks, serialized index, and EOF trailer.
CLI Usage Reference	`.topic_02_cli_commands`	Managing containers from the command line.
Deterministic SHA-256 Content Addressing and Verification	`.topic_03_integrity_verification`	Streaming SHA-256 manifest verification via Bakelite::Core::IntegrityVerifier and Bakelite.verify_archive.

Defined in:

bakelite/docs/d_containers/binary_containers.cr

Class Method Summary

.topic_01_container_layout : Nil
Binary Layout Specification: Organization of raw chunks, serialized index, and EOF trailer.
.topic_02_cli_commands : Nil
CLI Usage Reference: Managing containers from the command line.
.topic_03_integrity_verification : Nil
Deterministic SHA-256 Content Addressing and Verification: Streaming SHA-256 manifest verification via Bakelite::Core::IntegrityVerifier and Bakelite.verify_archive.

Class Method Detail

def self.topic_01_container_layout : Nil #

Binary Layout Specification: Organization of raw chunks, serialized index, and EOF trailer.

The binary container is organized into three regions:

Chunk Data Payloads: Sequentially packed compressed byte chunks.
JSON Index: Volume definitions, item metadata, chunk offsets, and CRC32 checksums.
32-Byte Trailer: Fixed-size footer containing magic bytes (BKLEND\x00\x00), 64-bit volume start offset, 64-bit index offset, 32-bit index size, 16-bit format version, and 16-bit flags.

[View source]

def self.topic_02_cli_commands : Nil #

CLI Usage Reference: Managing containers from the command line.

The bakelite CLI provides full management of archives and executable overlays:

bakelite pack <target> <dir> [--mount PATH] [--append]: Packs files into an archive or appends to an executable.
bakelite list <target>: Renders an interactive table of volumes and files using Opal.
bakelite inspect <target>: Details container metadata, offsets, and trailer integrity.
bakelite verify <target> [--sha256 DIGEST]: Verifies CRC32 chunk checksums and deterministic SHA-256 manifest digests.
bakelite extract <target> <dest>: Extracts all files or a specific volume to disk.
bakelite docs: Compiles structured guides using Jasper.
bakelite version: Displays version information managed by Carbon.

[View source]

def self.topic_03_integrity_verification : Nil #

Deterministic SHA-256 Content Addressing and Verification: Streaming SHA-256 manifest verification via Bakelite::Core::IntegrityVerifier and Bakelite.verify_archive.

Bakelite provides deterministic SHA-256 content addressing across Item, Volume, and FS::Registry alongside the two-tier archive verification engine:

Tier 1 (Bakelite::Core::IntegrityVerifier): Streams compressed chunks in $O(\text{chunk_size})$ memory, validating container headers, index bounds, per-chunk CRC32 checksums, file-level CRC32s, SHA-256 content digests, and canonical bakelite-manifest-v1 SHA-256 manifest signatures.
Tier 2 (Bakelite.verify_archive): Declarative block DSL for asserting expected file SHA-256 digests, strict manifest policies, required files, and overall archive manifest signatures.

[View source]