Building & Exporting Projects
Relevant source files
The following files were used as context for generating this wiki page:
Building and exporting projects in Crucible involves compiling models into Intermediate Representation (IR), generating target-specific code artifacts, and producing documentation or upgrade guides. The system supports multiple output targets including language-specific SDKs (Rust, TypeScript, Go, Java, etc.), OpenAPI specifications, and infrastructure constructs like Terraform providers or CDK libraries.
Sources: crates/crucible-cli/src/main.rs:18-20, crates/crucible-cli/src/main.rs:205-300
Project Compilation and Freezing
The Crucible CLI provides commands to manage the lifecycle of a model package. Compilation lowers a Crucible language package into a JSON-based release snapshot format. Freezing records a specific version of a compiled model into a releases/ directory and updates a lock file to ensure future builds do not introduce breaking changes against that baseline.
Sources: crates/crucible-cli/src/main.rs:107-133, crates/crucible-cli/src/main.rs:518-542
Compilation Flow
The following diagram illustrates the process of transforming a Crucible model into a snapshot artifact.
The compilation process validates the model against defined policies and previous versions before outputting the final IR.
Sources: crates/crucible-cli/src/main.rs:444-500
Artifact Generation
Crucible generates code for various targets by projecting the model IR based on the intended audience (Internal or External). The CLI handles the dispatch to specific generators for languages and infrastructure tools.
Generation Targets and Capabilities
Generators check for specific model features called "capabilities" before emitting code. These include support for sparse collections, arbitrary precision decimals, and specific HTTP protocol features.
| Target | Description | Capabilities Required |
|---|---|---|
| SDKs | Native clients for Go, Java, C#, etc. | Depends on language (e.g., BigInteger, Sparse) |
| OpenAPI | REST JSON service documentation | OpenAPI 3.1 features |
| Terraform | Resource lifecycle providers | Provisioning bindings |
| Docs | Markdown references and metadata | mdBook layout, JSON Schemas |
Sources: crates/crucible-cli/src/main.rs:172-198, crates/crucible-cli/src/main.rs:205-240
Build and Export Sequence
The CLI coordinates the projection of the model for the target audience and the subsequent writing of files to the output directory.
The projector ensures that items marked as @internal are omitted for external audience targets unless explicitly requested.
Sources: crates/crucible-cli/src/main.rs:410-440, crates/crucible-cli/src/main.rs:608-620
Documentation and Documentation Export
The Docs target generates a comprehensive Markdown API reference. This includes detailed pages for operations, shapes, and permissions. When configured with --all-releases, the system documents every supported release in separate directories, providing a versioned reference site.
Sources: crates/crucible-cli/src/main.rs:172-189, crates/crucible-build/src/docs_output.rs:10-25
Key Documentation Files
- describe.json: Holds the entire API reference as data using the
crucible.describe/1format. - llms.txt: An index of pages formatted for consumption by LLM agents.
- SUMMARY.md: The table of contents used by mdBook to organize the generated Markdown files.
- sdks.json: Describes available SDKs for the model, enabling links from documentation to generated code.
Sources: crates/crucible-codegen-docs/src/markdown.rs:240-280, crates/crucible-build/src/docs_output.rs:36-45
Documentation Settings Table
| Setting | Type | Default | Description |
|---|---|---|---|
audience | Audience | External | Selects which API elements to document. |
schemas | Schemas | Inline | Determines how JSON Schemas are stored in describe.json. |
all_releases | Boolean | false | If true, generates a reference for every supported version. |
sdks | Path | None | Path to a crucible-sdk.toml to include SDK info. |
Sources: crates/crucible-build/src/docs_output.rs:17-34
Exporting Upgrade Guides
Upgrade guides are generated as Markdown documents to assist clients in migrating between two supported releases. These guides detail migrations, retired operations, sunsets, and new additions between the "from" and "to" versions.
Sources: crates/crucible-cli/src/main.rs:134-142, crates/crucible-codegen-docs/tests/upgrade.rs:5-15
Upgrade Guide Generation Logic
The generator refuses to create guides if the releases are unknown, reversed, or if only a single release exists.
Guides are deterministic; the same model and release pair always produce identical output.
Sources: crates/crucible-codegen-docs/tests/upgrade.rs:85-115
SDK Packaging and Metadata
Every generated SDK package includes a README.md and an AGENTS.md. The README provides human-readable installation and usage instructions, while AGENTS.md provides terse instructions for coding agents.
Sources: crates/crucible-codegen-common/src/guide.rs:5-20
Package Metadata Configuration
Users can customize the exported package using metadata options provided during generation.
pub struct Guide {
pub language: String,
pub install: Vec<String>,
pub manifest: Option<(String, String)>,
pub public_registry: bool,
pub auth: String,
pub metadata: PackageMetadata,
}
Sources: crates/crucible-codegen-common/src/guide.rs:36-70
Crucible uses this metadata to decide whether to show public installation commands or organization-specific release notes for private packages.
Sources: crates/crucible-codegen-common/src/guide.rs:88-110
Summary
Building and exporting projects within Crucible transforms Crucible models into functional code and documentation. The system ensures consistency across versions through freezing and automated compatibility checks. By supporting diverse targets—from native SDKs to LLM-ready documentation—Crucible facilitates the distribution and maintenance of stable, well-documented APIs across different engineering environments.