Makefile Targets & Environment

Target audience: Maintainers, Contributors Goal: Reference for all Make targets and environment variables used in the StageX build system.

Environment Variables

Build Control

Variable	Default	Description
`STAGES`	`pallet bootstrap core user`	Namespaces (stages) to build; drives the `all` target
`PROGRESS`	`auto`	BuildKit progress output style (`auto`, `plain`, `tty`)
`PLATFORM`	`linux/amd64`	Target platform for builds (e.g., `linux/arm64`)
`BUILDER`	auto-detected (`docker`)	Build backend executable
`CHECK`	`0`	Set to `1` to enable Containerfile syntax checking during build
`NOCACHE`	`0`	Set to `1` to ignore all existing build cache (`--no-cache`)
`IMPORT`	`0`	Set to `1` to automatically import and tag built packages as `:local` after build
`RELEASE`	(auto)	Release version string (`YYYY.MM.N`) for `publish-*` and `prep-release-branch` targets

Registry & Publishing

Variable	Default	Description
`REGISTRY`	`stagex`	Registry URL/namespace used to build and publish images
`REGISTRY_USERNAME`	`127.0.0.1:5000/stagex`	Username/namespace for `registry-*` targets
`SIGNATURES`	`git@codeberg.org:stagex/sigs.stagex.tools.git`	Git remote URL for the signatures repository

Reproducibility (exported via `src/global.mk`)

Variable	Value	Purpose
`TZ`	`UTC`	Timezone for deterministic timestamps
`LANG`	`C.UTF-8`	Locale for reproducible builds
`LC_ALL`	`C`	Locale for reproducible builds
`SOURCE_DATE_EPOCH`	`1`	Unix epoch timestamp for deterministic build timestamps
`BUILDKIT_MULTI_PLATFORM`	`1`	Enables BuildKit multi-platform builds
`DOCKER_BUILDKIT`	`1`	Enables Docker BuildKit frontend

Computed Flags

Variable	Derivation	Description
`NOCACHE_FLAG`	`--no-cache` when `NOCACHE=1`, else empty	Passed to `docker build`
`CHECK_FLAG`	`--check` when `CHECK=1`, else empty	Passed to `docker build`

GPG / Signing

Variable	Default	Description
`STAGEX_GPG`	`gpg`	GPG binary for key listing and verification
`STAGEX_GPG_SIGN`	`${STAGEX_GPG}` (i.e. `gpg`)	GPG binary for signing operations
`STAGEX_GPGV`	`gpgv`	GPG verify binary

Top-Level Targets

Target	Description	Depends On	What It Does
`all`	Build entire tree (default)	`$(STAGES)`	Builds every package across all four stages
`check`	Run syntax checking and linting	(re-invokes `all` with `CHECK=1`)	Rebuilds entire tree with `--check` on every Docker build
`verify`	Verify local build against committed digests	—	Checks that each locally built OCI manifest digest has valid GPG signatures from maintainers in the signatures repository
`digests`	Generate digest files from full build tree	`all`	Runs `src/digests.py` to scan `out/**/index.json` and writes `digests/<stage>.txt` files
`new-digests`	Show newly changed digests	`digests`	Runs `git diff --minimal digests/*` to show only new/modified digest lines
`sign`	Sign all digests matching locally built targets	`digests`	Runs `src/sign-all.sh $(REGISTRY) $(RELEASE)` to create PGP sigstore signatures
`compat`	Check system compatibility	—	Runs `src/compat.sh` to verify tool versions (bash, docker, buildx, jq, gpg, containerd)
`preseed`	Seed build cache from last published release	—	Runs `src/preseed.sh` to pull published images into local Docker cache
`fetch`	Fetch and hash-verify all external sources	—	Runs `src/fetch.py` to download and verify SHA-256 hashes of all source tarballs
`prep-release-branch`	Prepare branch for new release	—	Runs `src/prep-release-branch.sh $(RELEASE)` to create a `release/YYYY.MM.N` branch
`help`	Display formatted help	—	Runs `src/help.sh Makefile` to parse and display targets/variables with descriptions

Infrastructure Targets

Defined in src/global.mk — support the auto-generated per-package build system.

Target	Description	What It Does
`default`	Default goal	Regenerates target list then builds everything
`targets`	Regenerate auto-generated targets	Runs `src/targets.py > out/targets.mk` to generate per-package Make targets from `package.toml` files
`out`	Create output directory	`mkdir out`
`content-<name>`	List package contents	Runs `ls -R out/<name>` and `tar -tvf` on the largest file
`digests-<name>`	Show digests for a specific package	Runs `src/package-digests.py <name>` to extract and display OCI manifest digests

Auto-Generated Per-Package Targets

Generated by src/targets.py for every package found in packages/<stage>/<name>/Containerfile.

Aggregate Stage Targets

Target	Builds
`bootstrap`	All bootstrap packages
`core`	All core packages
`pallet`	All pallet packages
`user`	All user packages

Single-Package Targets

Target	Example	What It Does
`<name>`	`pallet-rust`	Build package by short name (shorthand for `<stage>-<name>`)
`<stage>-<name>`	`core-rust`	Build stage-specific package via Docker/BuildKit with OCI output
`import-<stage>-<name>`	`import-core-rust`	Import built image to local OCI store via `docker load`, tag as `:local`
`registry-<stage>-<name>`	`registry-pallet-rust`	Build and push to registry via `type=image,push=true`
`publish-<stage>-<name>`	`publish-pallet-rust`	Publish to Docker Hub + Quay.io (requires ≥ 2 signatures)

Aggregate Publish

Target	Description
`publish`	Publish all packages (aggregate of all individual `publish-*` targets)

Build Recipe Details

Each per-package build (out/<stage>-<name>/index.json) follows this recipe:

Source fetch — Creates fetch/<stage>/<name>/, runs src/fetch.py <package_toml> to download and verify SHA-256 hashes of all source tarballs
Docker build — Invokes $(BUILDER) build with:
--ulimit nofile=2048:16384
--tag stagex/<stage>-<name>:<version>
--provenance=false
--build-arg SOURCE_DATE_EPOCH=1 BUILDKIT_MULTI_PLATFORM=1
--output type=oci, tar=true, dest=- with rewrite-timestamp=true, force-compression=true
--platform=$(PLATFORM) --progress=$(PROGRESS)
$(NOCACHE_FLAG) $(CHECK_FLAG)
-f packages/<stage>/<origin>/Containerfile packages/<stage>/<origin>
Output extraction — Pipes BuildKit output through tar -C out/<stage>-<name> -mx
Optional import — If IMPORT=1, runs the import macro (tar + docker load + tag)

Build-Time Arguments Injected

From package.toml source definitions:

Argument	Source
`VERSION`, `VERSION_UNDER`, `VERSION_DASH`, `VERSION_MAJOR`, `VERSION_MAJOR_MINOR`, `VERSION_STRIP_SUFFIX`	Package version string
`<SOURCE_NAME>_VERSION`, `<SOURCE_NAME>_SOURCE`, `<SOURCE_NAME>_GIT_SHA`	Per-source metadata
`--build-context fetch=fetch/<stage>/<name>`	Local fetch directory context
`--build-context stagex/<dep>=oci-layout://./out/<dep>`	Build dependency resolution
`--target package-<name>`	Multi-stage build target (where applicable)

Version Requirements

Checked by make compat via src/compat.sh:

Tool	Minimum Version	Notes
Bash	5.0	macOS users may need `brew install bash`
Docker Engine	29.1.5	Must have containerd image store enabled
Docker Buildx	0.30.1	Included in Docker Desktop; separate plugin on Linux
jq	1.6	Command-line JSON processor
GPG (gnupg)	2.2	Required for signing and verification