mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
e6e0f3dd6d
Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0 jargon, references to non-existent commands, stale CI snippets). New documentation (6 files), written from repository source analysis: - docs/architecture.md — crate graph, engine lifecycle, identity computation, runtime backends, store design, WAL, GC, unsafe blocks - docs/cli-reference.md — all 23 commands with syntax, args, flags, exit codes, env vars, verified against crates/karapace-cli/src/main.rs - docs/storage-format.md — directory layout, objects, layers, metadata, manifest format, lock file, WAL, atomic write contract - docs/security-model.md — mount/device/env var policies with exact defaults from security.rs, trust assumptions, what is NOT protected - docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo profile, reproducibility verification, toolchain pinning - docs/contributing.md — setup, verification, project layout, code standards, testing, CI workflows README.md rewritten: concise, no marketing language, prerequisites first, usage example, command table, limitations section. CONTRIBUTING.md now points to docs/contributing.md. CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.
83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# Build and Reproducibility
|
|
|
|
## Deterministic identity
|
|
|
|
The environment identity (`env_id`) is a blake3 hash computed from the fully resolved lock file — not from the unresolved manifest. Two identical lock files on any machine produce the same `env_id`.
|
|
|
|
The identity is computed in `karapace-schema/src/lock.rs::LockFile::compute_identity()`. See [architecture.md](architecture.md) for the full list of hash inputs.
|
|
|
|
## Lock file
|
|
|
|
`karapace build` writes `karapace.lock` next to the manifest. This file pins:
|
|
|
|
- Base image content digest (blake3 of rootfs)
|
|
- Exact package versions (queried from the package manager inside the image)
|
|
- All manifest-declared settings (hardware, mounts, backend, resource limits)
|
|
|
|
The lock file should be committed to version control.
|
|
|
|
## Reproducibility constraints
|
|
|
|
Given the same lock file and the same base image content, builds produce the same `env_id`. The overlay filesystem content depends on the package manager's behavior, which Karapace does not control.
|
|
|
|
Karapace guarantees identity reproducibility (same inputs → same `env_id`). It does not guarantee bit-for-bit filesystem reproducibility across different package repository states.
|
|
|
|
## CI release builds
|
|
|
|
Configured in `.github/workflows/ci.yml` and `.github/workflows/release.yml`.
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Value | Purpose |
|
|
|----------|-------|---------|
|
|
| `CARGO_INCREMENTAL` | `0` | Disable incremental compilation |
|
|
| `SOURCE_DATE_EPOCH` | `0` | Deterministic timestamps in build artifacts |
|
|
|
|
### RUSTFLAGS
|
|
|
|
```
|
|
-D warnings
|
|
--remap-path-prefix /home/runner/work=src
|
|
--remap-path-prefix /home/runner/.cargo/registry/src=crate
|
|
--remap-path-prefix /home/runner/.rustup=rustup
|
|
```
|
|
|
|
Path remapping eliminates runner-specific filesystem paths from the binary.
|
|
|
|
### Cargo profile (release)
|
|
|
|
Defined in workspace `Cargo.toml`:
|
|
|
|
```toml
|
|
[profile.release]
|
|
strip = true
|
|
lto = "thin"
|
|
```
|
|
|
|
### Build procedure
|
|
|
|
1. `cargo clean` — eliminates stale intermediate artifacts
|
|
2. `cargo build --release --target <target> -p karapace-cli -p karapace-dbus`
|
|
|
|
Both glibc (`x86_64-unknown-linux-gnu`) and musl (`x86_64-unknown-linux-musl`) targets are built. Musl binaries are fully statically linked.
|
|
|
|
### Reproducibility verification in CI
|
|
|
|
CI runs two types of reproducibility checks:
|
|
|
|
- **Same-run:** two sequential builds on the same runner, output hashes compared
|
|
- **Cross-run:** builds on `ubuntu-latest` and `ubuntu-22.04`, hashes compared (warning-only — different system libraries may cause differences in glibc builds)
|
|
|
|
Musl builds are expected to be runner-independent.
|
|
|
|
**Constraint:** build invocations must use identical `-p` flags. Building `-p karapace-cli` alone may produce a different binary than `-p karapace-cli -p karapace-dbus` due to codegen unit ordering.
|
|
|
|
## Local development builds
|
|
|
|
`.cargo/config.toml` configures path remapping for the project maintainer. Other developers should update the paths or set `RUSTFLAGS` directly.
|
|
|
|
Local builds are for development. CI builds are the authoritative release artifacts.
|
|
|
|
## Pinned toolchain
|
|
|
|
CI pins Rust toolchain version via `RUST_TOOLCHAIN` environment variable (currently `1.93`). This is set in the workflow `env` block and used with `dtolnay/rust-toolchain@stable`.
|