Nimble lockfile and Nim compiler version interoperability for reproducible builds

Question

Goal: ensure that a Nimble lockfile captures the exact Nim compiler version used during dependency resolution so that rebuilding the project on any machine yields bit‑identical binaries.
Currently, Nimble writes package versions and source URLs to nimble.lock but omits the compiler version; the minNimVersion field in nimble.yml only specifies a minimum version, leaving patch‑level changes unrecorded and making builds potentially sensitive to compiler‑specific features or ABI shifts.
The Nim community debates whether extending the lockfile schema to include a compiler version hash would improve reproducibility at the cost of flexibility, and how such a change would affect existing projects that rely on the current lockfile format.
Should Nimble extend the lockfile to store an exact compiler version hash? What trade‑offs arise between guaranteed reproducibility and the ability to use newer, backward‑compatible compiler releases? How would a schema change impact existing lockfiles and downstream tooling?

Tasadduq Burney · Answer

Direct answer
Do not extend nimble.lock with a mandatory compiler hash. An optional, backward-compatible field—or, preferably, an external environment manifest—is the safer path for reproducible Nim builds.

Confirmed facts

nimble.lock records dependency versions and source URLs, but not the Nim compiler version.
minNimVersion in nimble.yml is a lower bound, not a pin.
Official Nim releases do not provide a stable compiler hash; only a version string or a git commit from a source build is reliably available.

Likely explanation
Nim patch releases can alter generated C code or standard-library behavior. Even minor version drift may therefore change the final binary. However, bit-identical output also depends on the C compiler, linker, nimcache paths, and build flags. A compiler hash inside the lockfile is insufficient by itself.

Trade-offs

ApproachReproducibilityFlexibilityMigration risk

Mandatory compiler hashHighLow—blocks new patch releasesHigh—breaks strict parsers
Optional compilerVersion stringMediumHighLow—additive change
External environment manifestHigh (full toolchain)HighNone

Schema impact
An additive optional field keeps existing lockfiles valid. Strict third-party tooling may reject unknown fields; tolerant parsers or an explicit lockfile format version reduce that risk. A mandatory hash would force every downstream consumer to update.

Steps for this case

Keep nimble.lock for dependency resolution only.
Record the exact Nim version and C toolchain in a separate manifest (for example, a Dockerfile digest, Nix expression, or CI variable).
If you must extend the lockfile, add an optional compilerVersion string rather than a hash.
Before rolling out a schema change, verify that your Nimble version and CI tools tolerate unknown fields.

Missing diagnostic
Do you control the C compiler, linker, and build flags in your build environment, or only the Nim version? If the full toolchain is not controlled, compiler pinning in the lockfile will not yield bit-identical binaries regardless of schema changes.

Nimble lockfile and Nim compiler version interoperability for reproducible builds

1 answer

Direct answer

Confirmed facts

Likely explanation

Trade-offs

Schema impact

Steps for this case

Missing diagnostic

Your perspective belongs here.

0 question comments

Approach	Reproducibility	Flexibility	Migration risk
Mandatory compiler hash	High	Low—blocks new patch releases	High—breaks strict parsers
Optional `compilerVersion` string	Medium	High	Low—additive change
External environment manifest	High (full toolchain)	High	None