Package workstation tools, reuse emulator sessions, and derive build versions
This commit is contained in:
@@ -80,3 +80,5 @@ cartridge creation: new payloads contain installed Void package trees.
|
||||
- [troubleshooting](troubleshooting.md)
|
||||
- [workstation-tooling-plan](workstation-tooling-plan.md)
|
||||
- [workstation](workstation.md)
|
||||
|
||||
- [Git-derived build versions and Arch packaging](versioning.md)
|
||||
|
||||
@@ -46,7 +46,10 @@ indexing also explicitly sets `XBPS_ARCH=aarch64`.
|
||||
|
||||
## Generic Linux workstation tools and desktop additions
|
||||
|
||||
`make workstation` builds native `fds-cartridge` and `fds-emulator`. Runtime
|
||||
`make workstation` builds the Arch `fds-tools` package; `make workstation-install`
|
||||
installs it with pacman. `make workstation-binaries` builds native `fds-cartridge`
|
||||
and `fds-emulator` on generic Linux. Python 3 and Git resolve build versions;
|
||||
Dasung builds install these tools in the project-local Void container as well. Runtime
|
||||
requirements are QEMU, erofs-utils, bubblewrap and native XBPS with a prepared
|
||||
Void source checkout for software creation. `fds-cartridge` invokes xbps-src,
|
||||
installs runtime dependencies and creates direct EROFS trees. The Rust tar reader
|
||||
|
||||
@@ -141,7 +141,7 @@ The JSON document has exactly these fields:
|
||||
|
||||
This is a schema illustration, not a usable manifest: the size and hash
|
||||
placeholders must be replaced with values from the actual artifact. Format 1
|
||||
accepts the current tool version, a positive source epoch, a 40-character Void
|
||||
accepts a bounded numeric-leading release/development version, a positive source epoch, a 40-character Void
|
||||
commit, and 1–64 nonempty artifacts. Filenames must be flat safe ASCII names;
|
||||
paths, duplicates, hidden names, reserved manifest filenames and unknown fields
|
||||
are rejected. The manifest is bounded to 1 MiB. Files must be regular files,
|
||||
|
||||
@@ -10,7 +10,8 @@ entry point. Both executables cross-build as static-musl AArch64 programs. The
|
||||
normal OS continues to use glibc; no target musl runtime package is added.
|
||||
|
||||
For native Linux software packaging and QEMU hotplug, use `make workstation`
|
||||
and the [workstation guide](workstation.md). Those Clap tools are host binaries;
|
||||
on Arch, or `make workstation-binaries` on other Linux distributions, and follow
|
||||
the [current workstation guide](../workstation.md). Those Clap tools are host binaries;
|
||||
`make tooling` below builds the static ARM runtime tools.
|
||||
|
||||
## Build and test
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# 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.
|
||||
@@ -22,3 +22,8 @@ unchanged. Build new matching artifacts and record their hashes and source input
|
||||
See [user instructions](../workstation.md) and [format reference](../software-format.md)
|
||||
for the supported interface. Historical xz acceptance remains in
|
||||
[the earlier workstation record](workstation-validation.md).
|
||||
|
||||
The Arch distribution package is `fds-tools`, built by `make workstation` and
|
||||
installed by `make workstation-install`. `make workstation-binaries` preserves
|
||||
the generic Linux build. Stopped emulator directories support a fresh boot while
|
||||
retaining logs, DATA overlays and archived cartridge mappings.
|
||||
|
||||
@@ -3,7 +3,11 @@
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
This guide uses a **Linux workstation**, not the Raspberry Pi. It takes you from
|
||||
This page records the earlier archive-based software prototype. For installed
|
||||
Void software trees, the Arch `fds-tools` package, and reusable emulator sessions,
|
||||
follow the [current walkthrough](../workstation.md).
|
||||
|
||||
This historical guide uses a **Linux workstation**, not the Raspberry Pi. It takes you from
|
||||
source software to a cartridge disk image, runs that image in FDS, and explains
|
||||
how to write the same complete image to USB. All commands run from the checkout
|
||||
root unless marked as guest commands.
|
||||
|
||||
@@ -33,5 +33,7 @@ fds --json bay 01
|
||||
```
|
||||
|
||||
To inspect a stopped emulator, read its saved logs directly on the workstation.
|
||||
Rebooting uses a new session directory; existing DATA overlays remain in the old
|
||||
session and can be [exported](workstation.md#save-emulator-data).
|
||||
Run `start` again with the same session directory and boot options after `stop`.
|
||||
Logs and DATA overlays are retained; bays start empty. Saved DATA can be
|
||||
[exported](workstation.md#save-emulator-data). If restart reports a live process,
|
||||
check `status` and stop the existing VM before retrying.
|
||||
|
||||
+45
-5
@@ -7,15 +7,42 @@ as guest commands.
|
||||
|
||||
## Prepare the tools
|
||||
|
||||
The native tools are `fds-cartridge` and `fds-emulator`. Build them with Rust,
|
||||
a C linker and Make; the repository selects its pinned Rust toolchain:
|
||||
The native tools are `fds-cartridge` and `fds-emulator`. On Arch Linux, build
|
||||
and install their `fds-tools` package from the checkout:
|
||||
|
||||
```sh
|
||||
sudo pacman -S --needed base-devel rustup python git
|
||||
make workstation
|
||||
mkdir -p out
|
||||
make workstation-install
|
||||
```
|
||||
|
||||
`make workstation` produces `out/workstation/fds-tools-VERSION-1-ARCH.pkg.tar.zst`
|
||||
with both commands, documentation, examples and license notices. It does not
|
||||
install packages. `make workstation-install` builds that package and invokes
|
||||
`sudo pacman -U` to install it into `/usr/bin`. Pacman tracks upgrades and removal;
|
||||
remove it later with `sudo pacman -R fds-tools`. The exact latest package path is
|
||||
recorded in `out/workstation/package-path.txt`.
|
||||
|
||||
The package requires glibc, GCC runtime libraries and xz. EROFS, bubblewrap and
|
||||
QEMU are optional package dependencies because the tools can use the project-local
|
||||
Void runners instead. For all features using native Arch utilities, install:
|
||||
|
||||
```sh
|
||||
sudo pacman -S --needed bubblewrap erofs-utils qemu-system-aarch64 qemu-img
|
||||
```
|
||||
|
||||
On other Linux distributions, install Rust, a C linker, Make, Python 3 and Git,
|
||||
then build the same native commands without Arch packaging:
|
||||
|
||||
```sh
|
||||
make workstation-binaries
|
||||
export PATH="$PWD/out/workstation:$PATH"
|
||||
```
|
||||
|
||||
Python and Git resolve the build version; neither is needed to run the installed
|
||||
Rust commands. The repository selects its pinned Rust toolchain. XBPS and a
|
||||
prepared Void checkout are still separate source-build prerequisites.
|
||||
|
||||
| Prerequisite | Used for |
|
||||
| --- | --- |
|
||||
| Prepared writable Void `void-packages` checkout and native XBPS utilities | Build source packages and install their AArch64 runtime dependencies |
|
||||
@@ -138,7 +165,9 @@ fds-emulator --session out/my-emulator start \
|
||||
--system /path/to/fds-system-cli.img
|
||||
```
|
||||
|
||||
The session directory must be new and private. Keep its absolute path short
|
||||
The session directory is created private (0700). After stopping, reuse the same
|
||||
directory with the same `start` command; an existing directory must contain a
|
||||
valid stopped FDS session owned by you. Keep its absolute path short
|
||||
(under 90 bytes) for Unix sockets. Start waits for the FDS prompt and uses two
|
||||
emulated CPUs and 1024 MiB RAM; `--memory-mib 2048` increases memory. SYSTEM and
|
||||
PROGRAM images are read-only. The session holds logs and any DATA overlays.
|
||||
@@ -181,7 +210,18 @@ fds-emulator --session out/my-emulator stop
|
||||
|
||||
Eject asks FDS to stop programs and release storage before removing the virtual
|
||||
USB device. If FDS refuses, the cartridge stays attached. `stop` performs native
|
||||
FDS shutdown. Session logs remain available; create a new session to boot again.
|
||||
FDS shutdown and waits for QEMU to exit. Start the same session again:
|
||||
|
||||
```sh
|
||||
fds-emulator --session out/my-emulator start --qemu-runner tools/in-void
|
||||
```
|
||||
|
||||
Pass any custom boot-image or memory options again. This is a fresh boot with
|
||||
empty cartridge bays. Console and QEMU logs are appended, DATA overlay files
|
||||
remain in place, and `previous-*.json` preserves the previous session's image
|
||||
and overlay mapping. Insert cartridges again as needed. A running session,
|
||||
unknown directory, insecure permissions, or an outstanding control operation
|
||||
prevents restart; the tool never clears a live session to make room.
|
||||
|
||||
`unplug BAY` simulates a physical pull, and `stop --force` cuts virtual power.
|
||||
Use these only for deliberate failure simulation; DATA writes can be lost.
|
||||
|
||||
Reference in New Issue
Block a user