= packed-metanorma — Metanorma single-executable packages (tebako v2)
image:https://github.com/metanorma/packed-metanorma/workflows/build/badge.svg["Build Status", link="https://github.com/metanorma/packed-metanorma/actions/workflows/build.yml"]
== Purpose
This repository assembles the single-executable Metanorma packages
published on the releases page. It assembles — it compiles nothing.
Every input is a published, sha256-pinned release artifact, and the whole
pipeline is one workflow (.github/workflows/build.yml):
. fetch — the tebako toolchain and the payload slices, verified against
the digests pinned in versions.yaml;
. assemble — tebako-pkg bundle stitches the slices onto the tebako
bootstrap;
. validate — structural trailer gates, a --version smoke run, and a
PDF-compile diagnostic;
. publish — on tags, a GitHub release plus dispatches to the downstream
packagers (snap, Homebrew, Chocolatey, winget).
The v1 era (six platform workflows driven by Makefiles, compiling Ruby
from source on every build) is retired; this repo is now a thin assembly
layer over the tebako v2 ecosystem.
== What a package is (tebako v2 in one paragraph)
A package is up to three independently distributable parts, glued by the
tpkg trailer:
- Bootstrap — the tiny Rust loader that is the process entry point;
- Runtime — the Ruby interpreter executable plus its environment image
(stdlib + gems), two artifacts downloaded once per machine into the
shared
~/.tebako cache, sha256-verified, mounted (never extracted);
- Payload slices — bare
.tfs filesystem images. packed-metanorma carries
the metanorma app itself, an OpenJDK runtime (for mn2pdf), and the
xml2rfc payload with its bundled python runtime.
The packages built here are lean: the payloads ride inside the
executable, and the runtime pair is resolved on first run from the
pinned release and then cached forever. The authoritative architecture
documentation lives in docs/spec/00–19 of the tamatebako/tebako
repository.
== Inputs — versions.yaml is the single source of truth
Every byte the pipeline assembles is pinned in versions.yaml:
[cols="1,2",options="header"]
|===
| Input | Currently pinned
| tebako toolchain (tamatebako/tebako)
| v2.8.22 (tebako-pkg, tebako-bootstrap, tfs per platform)
| Ruby runtime (tamatebako/tebako-runtime-ruby)
| runtime 0.16.31 / ruby 4.0.7 (resolved at first run)
| metanorma payload (tebako-packages/metanorma)
| 1.17.0 (release tag 1.17.0-3)
| OpenJDK slice (tamatebako/tebako-runtime-openjdk)
| 21.0.12 (release tag v2.8.21)
|===
Bumping any input is a one-line edit of versions.yaml; the workflow,
the manifest template, and the release notes all flow from it (nothing
else in the repo hardcodes a version or a digest). The package manifest
template lives in package/package-manifest.yaml and is rendered by
tools/render-manifest with values from tools/pins.rb.
== Using a package
Download the asset for your platform from the release page:
- macOS (Apple Silicon):
metanorma-darwin-arm64.tgz
- Linux (x86_64):
metanorma-linux-x86_64.tgz
- Windows (x86_64):
metanorma-setup-<version>-windows-ucrt64.msi
(signed installer; portable metanorma-windows-x86_64.exe, also as
.zip)
Unpack (macOS/Linux) and run:
[source,console]
$ tar xzf metanorma-darwin-arm64.tgz
$ ./metanorma-darwin-arm64 --version
On first run the package downloads the Ruby runtime pair (interpreter +
environment image, sha256-verified) into ~/.tebako and caches it
machine-wide; later runs start immediately. No compilation machinery, no
system dependencies.
== Downstream channels
Besides the assets attached to each release, the signed Windows MSI
installer is published to the
https://learn.microsoft.com/windows/package-manager/[Windows Package
Manager] community repository as Metanorma.Metanorma, so Windows users
can install and keep Metanorma up to date with winget install Metanorma.Metanorma. The submission is automated by the
winget-publish workflow, which builds the winget manifest from the MSI
attached to a release and opens a pull request to
microsoft/winget-pkgs; a new version appears on winget once that pull
request is reviewed and merged there.
== Development
=== Layout
versions.yaml — pin SSOT (see above)package/package-manifest.yaml — L2 package manifest template
(@@PLACEHOLDER@@ values filled from versions.yaml)tools/pins.rb — reads versions.yaml, emits the env a build leg
needs (ruby tools/pins.rb <triplet> <tool-platform> --env)tools/render-manifest — renders the manifest templatetools/sync-payload.rb — flows a new metanorma payload version from
the feedstock registry into versions.yaml (used by the dispatch flow)fixtures/r060-1/ — the OIML document the PDF-compile diagnostic
builds.github/workflows/build.yml — the whole pipeline
=== Bumping the metanorma payload
The tebako-packages/metanorma feedstock sends a
repository_dispatch (tebako-packages/metanorma) when it publishes a
new payload. The prepare job then fetches the feedstock registry,
rewrites the metanorma block of versions.yaml, commits to main, and
tags v<version> — the tag push runs the full pipeline and publishes
the release. The same flow can be started by hand with
workflow_dispatch (payload_version input). Bumping the OpenJDK /
xml2rfc slices or the tebako/runtime pins is a manual one-line edit of
versions.yaml on a PR.
== Known limitations
- PDF output is blocked by an upstream tebako gap. tebako v0.2.4
hands mounted payload regions to spawned child processes via
TEBAKO_TFS_MOUNTS as bare image:mount pairs; the child then tries
to mount the whole package file at the payload's mount point and
fails:
libtfs-preload: TEBAKO_TFS_MOUNTS: cannot mount at /opt/openjdk: Invalid argument
Since metanorma compile shells out to the mn2pdf JVM (which lives in
the OpenJDK slice) regardless of output format, any compile hits this.
The workflow's PDF leg is therefore a non-blocking diagnostic that
fails the build on any other error signature. The fix is a tebako
mounts-grammar extension (the C ABI already has
tebako_fs_mount_from_file_at); once a tebako release carrying it is
pinned in versions.yaml, flip the leg's continue-on-error off.
-
Windows runtime resolution is blocked by an upstream naming
mismatch. tebako-runtime-ruby v0.16.9 publishes the windows
interpreter as tebako-runtime-0.16.9-3.3.12-windows-ucrt64 (no
.exe) and its manifest.json agrees, but tebako-bootstrap v0.2.4
looks the asset up as …-ucrt64.exe and its contract gate refuses:
runtime "[email protected];tebako=0.16.9;image" is pre-era … (no entry for tebako-runtime-0.16.9-3.3.12-windows-ucrt64.exe) (exit 75). POSIX
platforms are unaffected. The workflow's windows smoke step is a
non-blocking diagnostic gated on exactly this signature until a
runtime/toolchain pair with matching windows naming is pinned.
-
Windows executable ships without a file icon. Resource embedding is
pending in the tebako toolchain (the v1 resources.win/ mechanism
does not apply to the Rust bootstrap).
-
Windows CA bundle. The runtime image does not expose its CA bundle
to the host JVM (tebako#437); the workflow extracts ssl/cert.pem
from the cached runtime image and points SSL_CERT_FILE at it during
the compile diagnostic.
-
First run needs the network. Lean packages resolve the runtime pair
on first run (one-time, cached afterwards).
== License
See the upstream Metanorma project for licensing terms.
