|
bashdeps
Exact dependency materialization and manifest maintenance tools
|
Accepted
This ADR defines how consuming projects obtain bashdeps.bash itself and how Make targets should separate dependency convergence, verification, and ordinary build work.
A dependency tool cannot use itself to obtain the first copy of itself. Every consumer therefore retains one intentionally small bootstrap path for the pinned bashdeps.bash release artifact.
The project does not attempt to hide this bootstrap paradox. Its value is that a small, repeated bootstrap recipe can replace many project-specific dependency recipes after bashdeps.bash is available.
The Make boundary also matters. A target advertised as offline verification must not silently download the tool required to perform that verification, and an ordinary build should not unexpectedly repair or fetch dependencies.
bashdeps.bash itself outside dependency destinations managed by the consumer manifest.A consuming project SHOULD place its bootstrapped bashdeps.bash artifact outside the paths managed by dependencies.txt.
The recommended location is:
The exact bootstrap directory is a consumer convention rather than a requirement of the bashdeps.bash CLI.
The consumer Makefile SHALL pin the bootstrap artifact by immutable release URL and committed SHA-256 digest. The release publishes bashdeps.bash.256 as a checksum companion for review and verification, but the consuming project SHALL retain its expected digest as committed trust data rather than dynamically trust a remote checksum file on every bootstrap.
The bootstrap recipe SHALL:
The bootstrap recipe MAY use the same downloader and SHA-256 capability-selection strategy documented by bashdeps, but it remains intentionally small and local to the consumer because bashdeps.bash is not yet available to implement that first step.
The recommended consumer contract SHALL be:
make deps MAY access the network and MAY mutate declared dependency destinations.
make deps-check SHALL NOT bootstrap a missing bashdeps.bash artifact. If the pinned bootstrap artifact is absent or invalid, the target SHALL fail rather than silently access the network or repair it. When the bootstrap artifact is valid, deps-check SHALL invoke bashdeps.bash verify and therefore remain network-free and non-mutating with respect to managed dependencies.
make build SHALL NOT implicitly invoke bashdeps.bash sync, bashdeps.bash verify, or the bootstrap recipe. A build may fail because required inputs are absent; that failure is preferable to an ordinary build unexpectedly changing repository state or requiring network access.
make all MAY compose deps followed by build for callers that explicitly want convergence before building.
Consumers MAY use different target names, but documentation for bashdeps SHOULD present this contract as the recommended integration because its boundaries map directly to the CLI semantics.
The bootstrap artifact SHALL be treated like any other externally acquired artifact: filename presence is insufficient. Consumers SHALL verify its pinned SHA-256 digest before trusting it.
A bootstrap recipe SHOULD avoid downloading when the existing bytes already match the pinned digest.
This creates a circular dependency: bashdeps.bash would be required to materialize the manifest entry that provides bashdeps.bash. The bootstrap artifact therefore remains outside the managed manifest.
This is convenient on a fresh checkout but violates the promised no-network and no-mutation character of a check operation. Explicit make deps is the repair path.
This makes first use convenient but couples compilation/generation to network and mutation. The project intentionally keeps ordinary build behavior separate from dependency convergence.
Committing the tool avoids bootstrap network access but creates generated/vendor copies whose update discipline can drift. Consumers remain free to choose that policy, but it is not the recommended integration.
A fresh checkout normally runs make deps before make build or uses make all.
Offline verification is meaningful only after the pinned bootstrap artifact is already available locally.
Consumers retain a small amount of duplicated bootstrap logic, but the larger and more security-sensitive dependency-set behavior is centralized in bashdeps.
The bootstrap recipe itself should be tested by consumers that rely on it because it remains outside bashdeps' runtime control.
A future release may provide a documented bootstrap snippet or generated Make include to reduce consumer duplication, but such a feature must not obscure the independent trust required for the first bashdeps.bash artifact.
1.9.8