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.

Defined in:

bakelite/docs/d_containers/binary_containers.cr

Class Method Summary

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:

  1. Chunk Data Payloads: Sequentially packed compressed byte chunks.
  2. JSON Index: Volume definitions, item metadata, chunk offsets, and CRC32 checksums.
  3. 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.

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>: Verifies CRC32 checksums for every chunk in the container.
  • 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.