module Bakelite::Docs::A_OVERVIEW::INTRODUCTION

Overview

Introduction to Bakelite

Bakelite is a zero-copy, streaming-capable virtual filesystem (BakedFS) for Crystal. It enables developers to embed assets directly into Crystal executables or append them post-compilation as binary containers, with first-class support for chunked compression, custom isolated volumes, union mounts, compile-time content-addressed transforms, and low-memory random-seeking IO.

Executive Summary & Key Topics

Topic Method / Anchor Description
Dual Storage Paradigm .topic_01_core_concepts Understanding the distinction between direct inlining and chunked streaming.
Key Architectural Features .topic_02_key_features Highlights of Bakelite's feature set.

Defined in:

bakelite/docs/a_overview/introduction.cr

Class Method Summary

Class Method Detail

def self.topic_01_core_concepts : Nil #

Dual Storage Paradigm: Understanding the distinction between direct inlining and chunked streaming.

Bakelite provides two primary storage primitives:

  • Bake (bake): Embeds bytes directly as static binary blobs into the Crystal executable. Zero decompression overhead and instantaneous random memory access. Ideal for small configuration files, shaders, templates, and crucial YAML/JSON definitions.
  • Store (store): Divides data into fixed-size chunks (e.g. 64KB), compresses each chunk individually (Deflate, Gzip, or Zlib), and streams them on demand through Bakelite::FileIO. Guarantees bounded memory usage regardless of file size (e.g. 2GB audio/video files stream in 64KB RAM).

def self.topic_02_key_features : Nil #

Key Architectural Features: Highlights of Bakelite's feature set.

  • Streaming IO: Implements standard Crystal IO with arbitrary seeking (Seek::Set, Seek::Current, Seek::End) across compressed chunk boundaries.
  • Custom Volumes & Union Mounts: Organize files into isolated volumes (Volume), mount them at prefixes, and layer them with priority shadowing.
  • Compile-Time Transforms: Built-in minification, line-ending normalization, and custom CLI pipelines cached by SHA-256 hash.
  • Post-Compile Binary Overlay: Append assets to precompiled executables or .bkl standalone archives without modifying host binary execution.
  • Rich Ecosystem Integration: Powered by sol-vin/carbon (versioning), sol-vin/opal (CLI terminal styling), and sol-vin/jasper (documentation compiler).