79 lines
4.5 KiB
Markdown
79 lines
4.5 KiB
Markdown
# Build versions and the workstation package
|
||
|
||
`tools/version` is the authoritative FDS build-version resolver. It reads this
|
||
repository's Git history, never the Void submodule's history. All FDS Rust
|
||
commands, base XBPS packages, login/boot banners and `/etc/os-release` use it.
|
||
SYSTEM cartridge metadata copies the version already embedded in its rootfs,
|
||
so wrapping an older rootfs does not mislabel it as the current source version.
|
||
|
||
Release tags are numeric `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`, optionally prefixed
|
||
with `v`. Unrelated tags are ignored. The nearest reachable release tag is used:
|
||
|
||
| Source state | Example build version |
|
||
| --- | --- |
|
||
| Exactly release tag `1.0`, clean checkout | `1.0` |
|
||
| Two commits after `1.0` | `1.0.r2.g123456789abc` |
|
||
| No reachable release tag | `0.dev.g123456789abc` |
|
||
| Uncommitted changes to tracked files | Append `.dirty` |
|
||
|
||
Untracked files do not affect the version, matching Git’s usual dirty-checkout
|
||
convention. Add new release sources to Git before tagging.
|
||
|
||
Versions are bounded to 32 letters, digits and periods, starting with a digit,
|
||
for the cartridge metadata, XBPS and Arch package formats. A shallow clone
|
||
without a reachable release tag gets a development version; fetch the intended
|
||
release tag/history before building a release. No value is silently invented
|
||
when both Git identity and an exported identity are missing.
|
||
|
||
Each Rust crate uses the shared build script, including direct Cargo builds.
|
||
Cargo notices tag/ref changes, index changes and source edits, avoiding an old
|
||
version string in a cached binary. Cargo's workspace metadata uses the SemVer
|
||
form `1.0.0`; the public build version comes from Git. Protocol/schema versions,
|
||
application recipe versions, the Linux kernel version and third-party package
|
||
versions are independent and remain unchanged.
|
||
|
||
`tools/prepare-void` writes the resolved value to the writable build checkout's
|
||
`fds-version` file. FDS-owned XBPS templates read it; base-files substitutes it
|
||
into `/usr/lib/os-release` and `/etc/issue`. `/etc/os-release` links to that
|
||
installed identity file. Runtime checks compare installed command versions
|
||
against `VERSION_ID`. Superseded FDS packages are archived under
|
||
`out/package-history/` so the active repository cannot accidentally select an
|
||
older development package whose version sorts above a release.
|
||
|
||
Frozen source exports save a validated `FDS_VERSION` file before inventorying
|
||
and hashing their contents. Their builds use that saved value without Git or
|
||
network access. Legacy 0.1.0 snapshots retain their original scripts and layout;
|
||
the historical release stays unchanged. Release verification accepts supported
|
||
version strings independently of the verifier's own version, so newer tools can
|
||
still authenticate an older signed release using the supplied trust key.
|
||
|
||
## Build and install on Arch
|
||
|
||
`packaging/arch/PKGBUILD` packages the local checkout. `make workstation` invokes
|
||
makepkg, building both binaries in the existing Cargo cache and recording the
|
||
result in `out/workstation/package-path.txt`. It builds without implicit package
|
||
installation; required build commands are checked directly. Runtime feature
|
||
packages are declared as optional because project-local runners are supported.
|
||
`make workstation-install` explicitly invokes pacman to install the exact
|
||
recorded package. Generic Linux users use `make workstation-binaries`.
|
||
|
||
The package includes binaries, the user/developer manuals, source examples,
|
||
MIT licensing and dependency notices. It has no service, hook or installation
|
||
script. The workflow follows the official [PKGBUILD specification](https://man.archlinux.org/man/PKGBUILD.5.en)
|
||
and [makepkg interface](https://man.archlinux.org/man/makepkg.8.en).
|
||
|
||
## Verification
|
||
|
||
`make check` includes release/no-tag/dirty/export and real Cargo cache-invalidation
|
||
checks. `make workstation-test` exercises the installed-tree cartridge creator;
|
||
`make emulator-test` covers stopping and starting the same directory, preserved
|
||
logs/overlays/mappings, and rejecting a restart of a live VM.
|
||
`make workstation-package-test` installs the real Arch package with pacman in a
|
||
disposable root and executes both installed commands. After building matching
|
||
images, `python3 tests/integration/version-images.py` reads the identity and
|
||
metadata directly from the GPT/EROFS image and executes its twelve FDS commands
|
||
under ARM emulation to compare their versions. Image acceptance
|
||
requires a new CLI rootfs and SYSTEM image: inspect their identity, execute the
|
||
ARM tools and run the VM checks. A VM result does not establish physical Pi or
|
||
Dasung power-cycle behavior.
|