Build Reproducibility
Control schema dependencies, generator executables, and build inputs without assuming byte-identical output.
Reproducible generation requires control over schema sources, dependency versions, generator executables, options, and the build environment. EasyP's lockfile verifies dependency inputs; it does not by itself guarantee hermetic or byte-for-byte reproducible output.
Three Inputs to Control
- Schema dependencies:
protobuf.lockrecords selected dependency versions, Git commits, andh1:content hashes. Commit it together withprotobuf.modand your own schemas. - Generator versions: Remote plugins require a pinned semantic
version. Local and bundled plugins reject that field: pin local executables in your build environment and pin the EasyP binary that contains bundled generators. - Execution environment: Keep plugin options and relevant environment variables consistent. A named built-in plugin can use an executable on
PATHinstead of the bundled WASM implementation. WASM and remote execution do not independently prove output determinism.
Workflow for Clean Repositories
After preparing the same EasyP and plugin versions used by the project, run from a fresh checkout with a root module and generator file:
easyp mod download
easyp generate --project .mod download installs and verifies the locked dependencies without selecting newer versions or rewriting the lock. Missing dependencies may require downloads. If locked content cannot be retrieved or verified, the command fails; it cannot guarantee that remote repositories remain available forever.
For multiple consumer projects, select them with repeated --project flags or explicitly use --all. Compare generated output in CI and run tests against it. When generated files are committed, a simple check is:
git diff --exit-code -- gen
test -z "$(git ls-files --others --exclude-standard -- gen)"Adapt gen to your tracked output directories. The second command catches new untracked files; ignored output is outside this check.
Local Replacements and Network Access
A local replace redirects one dependency to disk. It avoids dependency downloads only when the whole dependency graph is local or already present in verified cache. Unreplaced dependencies can still require downloads, and a remote generator still needs network access.
Local replacement contents are editable and are not pinned by the published dependency lock. With replacements, mod tidy validates an ephemeral effective graph and leaves the shared manifest/lock unchanged; get/mod update may edit explicit requirements but never write a local-graph lock. Remove replacements and publish the intended versions, then run mod tidy to resolve a release lock.
CI Practices
- Resolve intended dependency changes in a reviewed update, then use
easyp mod downloadin verification jobs.tidyandupdateare mutating commands, not a frozen verification mode. - Pin the EasyP binary, local plugin executables, and remote plugin versions using the mechanisms appropriate to each source.
- Keep generated-output checks and consumer tests: valid locks and semantic versions do not prove schema compatibility or identical output bytes.
See local replacement debugging and GitHub Actions.
Explicit frozen verification
easyp mod download --frozen
easyp generate --frozenFrozen mode validates existing manifests and locks, refuses all main-module local replacements, and never resolves new dependency versions or writes either file. It may fetch exact locked commits into the cache. It is not enabled by the CI environment. Mutating commands such as tidy/update refuse frozen execution; prepare the published graph first. See frozen configuration.