Overview

This is the documentation for the framework’s design and API.

New here? Getting started walks through a first flake step by step; Choosing a flake framework places caisson relative to plain flake-parts, flakelight, and snowfall-lib; the FAQ answers the questions the concept pages tend to raise.

Reference documents the exported surface: the Library functions and the Options.

Conventions: Repository layout describes the directory conventions the documentation and examples assume.

Concepts explain the machinery and the reasoning behind it, in reading order:

• Closed inputs: how modules and library overlays close over the defining flake’s inputs, and the explicit closure convention every registered thing follows.
• Module classes: class-keyed module registration and export.
• Library overlays: namespaced, dependency-declaring lib composition, and the patterns for writing overlays.
• Ecosystem sources: why integrations pin nothing, and the three places a source can come from.

Deep dives: How lib is composed traces a mkLib call from arguments to finished attrset, including the rules that decide conflicts and composing through caisson-core directly. How inputs are closed over traces the closure attrset from mkLib to a registered file, including what each kind of registration receives and which values cross flake boundaries.

Guides: Testing covers unit and integration testing (including callConsumerFlake), and Evaluation weight covers measuring and gating evaluation cost.

For a complete working flake with commentary, see examples/literate-flake/ in the repository. The repository README covers the quick start.

Despite the org name, caisson is an independent project and is not affiliated with, endorsed by, or sponsored by the NixOS Foundation. Nix and NixOS are trademarks of the NixOS Foundation.