Binary Versioning of imgforge and mpforge¶

The two Rust tools in the project — imgforge (Garmin IMG compiler) and mpforge (Polish Map tiler) — embed at compile time a version string calculated from the Git state of the repository. This page documents how to read the --version output, where it comes from, and how to produce a clean release.

TL;DR — reading the --version output¶

Both tools expose the version via the --version flag:

imgforge --version   # imgforge v0.4.3-49-geedfa8d-dirty
mpforge --version    # mpforge v0.4.2-49-geedfa8d

The string after the tool name is produced by git describe --tags --always --dirty, after stripping the imgforge- or mpforge- prefix:

For a simple provenance check, reading stops here. The following sections are for maintainers and contributors.

How the version is resolved (maintainer)¶

The string is injected into the binary via the GIT_VERSION compile-time environment variable, calculated by each crate's build script (tools/imgforge/build.rs, tools/mpforge/build.rs).

Priority order¶

The first valid candidate wins:

CI sources (environment variables)

Git sources (local commands)

Rust fallback

The retained value is published via cargo:rustc-env=GIT_VERSION=… then read at runtime by env!("GIT_VERSION"), wired to clap.

Git tag convention¶

The repository hosts two crates (imgforge, mpforge) in a monorepo. So that each can have its own release cycle without collision, tags are prefixed:

At compile time, build.rs strips these prefixes before generating the GIT_VERSION string: a tag imgforge-v0.4.3 produces v0.4.3 in the binary, not imgforge-v0.4.3.

The Cargo watcher (subtle trap)¶

As soon as a build.rs emits at least one cargo:rerun-if-changed=... directive, Cargo disables its default scan of the package directory. Without an explicit watcher on sources, build.rs does not re-execute when a .rs file is modified, and GIT_VERSION stays frozen at its value from the last build that actually re-ran git describe.

Both build.rs files therefore declare the following watchers:

When -dirty appears¶

The suffix comes from git describe --dirty, which only looks at files already tracked by Git.

Release workflow (maintainer)¶

To publish a new version of one of the two tools:

1. Version bump¶

# Example: imgforge 0.4.3 → 0.4.4
vim tools/imgforge/Cargo.toml   # version = "0.4.4"
cd tools/imgforge && cargo build --release   # regenerates tools/imgforge/Cargo.lock

Each crate has its own local Cargo.lock (no unified Cargo workspace).

2. Synchronize documentation references¶

Several site pages contain versioned wget URLs pointing to the corresponding Forgejo release. Update at the same time as the bump:

3. Commit + tag¶

git add tools/imgforge/Cargo.toml tools/imgforge/Cargo.lock site/docs/...
git commit -m "release(imgforge): v0.4.4"
git tag imgforge-v0.4.4

The push (commit + tag) is then done by the maintainer according to their usual workflow.

4. Binary build and publication (CI)¶

On tag arrival, .woodpecker/imgforge.yml (or mpforge.yml):

• detects CI_COMMIT_TAG=imgforge-v0.4.4, build.rs strips the prefix, GIT_VERSION=v0.4.4 injected;
• generates an automatic CHANGELOG from the range PREVIOUS_TAG..CI_COMMIT_TAG;
• publishes the imgforge-linux-amd64.tar.gz archive on the Forgejo release of the tag.

5. Sanity check¶

./target/release/imgforge --version
# Must display exactly: imgforge v0.4.4

Any other display (suffix -N-g<hash>, -dirty, or bare hash) indicates the build was not done on the exact tag.

Map ↔ tool ↔ tag consistency¶

The project publishes two categories of artifacts simultaneously:

The two systems are disjoint: the compiler version used to produce a map is not inscribed in the .img filename (it is in manifest.json under the build_params key of coverages).

To attest the provenance of an installed binary, {tool} --version and the corresponding Forgejo tag are the only reliable pair. If there is doubt about the map itself, consult the manifest.json published alongside the .img file.

Related pages: imgforge — the compiler · mpforge — the tiler