Documentation
¶
Overview ¶
Package substrate realizes the native BUILD ENVIRONMENT a build needs — C toolchains, build helpers, sysroots — as a peer of the toolchain layer, under the same ownership discipline: inferred (engines emit CAPABILITIES, never packages), realized by a backend (which alone knows distro/package semantics), cached on the persistent mount, and recorded as explicit provenance.
Invariants (load-bearing — do not erode):
- engines infer CAPABILITIES, not packages
- substrate owns realization
- the backend owns distro/package semantics
- operators declare intent, not incidental mechanics
- apk is the bootstrap TRANSPORT, not the architecture
- a realized substrate is EXPLICIT STATE (recorded), not ambient host mutation
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Need ¶
type Need struct {
Capability string // "c-toolchain", "cmake", "perl", "pkg-config", "openssl"
Reason string // why: "rust-build-script-linking", "crate-native-build"
Source string // who asked: "cargo", "aws-lc-sys"
}
Need is an inferred capability a build requires from its environment, carrying the reason and source so realization is explainable, provenance-able, and policy-able. A capability is abstract ("c-toolchain"), never a package ("build-base").
func InferRustNeeds ¶
InferRustNeeds derives the substrate capabilities a Rust build requires from the crate itself, NOT from operator config (discover, don't burden). Rust always needs a C toolchain — build scripts are themselves linked Rust executables, so even a pure-Rust crate fails with "linker cc not found". Specific crates pull additional native build deps, learned by scanning the resolved crate graph (Cargo.lock).
type PackageVersion ¶
PackageVersion is a realized package + its version — the explicit state that becomes build-identity provenance (a libc/cmake/perl version can matter for reproducibility and supply-chain response).
type Realized ¶
type Realized struct {
Need Need
Backend string
Packages []PackageVersion
Present bool // already satisfied — nothing installed this run
}
Realized is the explicit outcome of realizing one Need: which backend, which packages (with versions), or already-present.
type Realizer ¶
type Realizer interface {
Realize(ctx context.Context, needs []Need) ([]Realized, error)
Backend() string
}
Realizer realizes capabilities into the build environment. This interface is the swappable seam: engines depend on it, never on apk/alpine. The bootstrap backend is apk; content-addressed / OCI-backed / remote realizers plug in behind it unchanged.
func NewRealizer ¶
NewRealizer returns the realizer for the current build host. The apk backend (Alpine) is the bootstrap; on a host without apk it is a no-op that trusts the ambient environment (a dev workstation already has cc/cmake). cacheDir is the persistent package-cache root ("" disables caching) — keeping substrate offline- after-first alongside the toolchain and build caches.
Source Files