Files
muSRFlow/packaging/runtime/build-runtime-archive.py
T
salman b52e191082 Produce standalone runtime download bundles
Build a validated runtime snapshot into a reproducible tar.gz archive, JSON download descriptor, and SHA-256 sidecar. Publish complete content-addressed bundles without overwriting prior downloads and retain portable links and executable permissions.

Include the download format in Linux release commands, document user-local offline use, and cover archive checksums, extraction, repeat builds, support-file changes, and failure preservation. The app's runtime selection and fitting paths remain unchanged.
2026-10-25 17:38:17 +01:00

150 lines
6.8 KiB
Python

#!/usr/bin/env python3
# Copyright (C) 2026 Zaher Salman
# SPDX-License-Identifier: GPL-3.0-or-later
"""Produce a relocatable Linux runtime download and its verified description."""
import argparse
import gzip
import hashlib
import json
import os
from pathlib import Path
import shutil
import stat
import subprocess
import sys
import tarfile
import tempfile
def file_sha256(filename):
digest = hashlib.sha256()
with filename.open("rb") as stream:
while True:
block = stream.read(1024 * 1024)
if not block:
break
digest.update(block)
return digest.hexdigest()
def check_portable_tree(prefix):
# Absolute/external links work on the build machine but break when the
# download moves to a user's private runtime directory. Never follow them.
for directory, directories, files in os.walk(str(prefix), followlinks=False):
for name in directories + files:
entry = Path(directory) / name
mode = entry.lstat().st_mode
if stat.S_ISLNK(mode):
destination = Path(os.readlink(str(entry)))
if destination.is_absolute():
raise ValueError("runtime contains an absolute symlink: " + str(entry))
try:
entry.resolve(strict=True).relative_to(prefix)
except (ValueError, FileNotFoundError, RuntimeError):
raise ValueError("runtime contains an external, broken, or cyclic symlink: " + str(entry))
elif not stat.S_ISREG(mode) and not stat.S_ISDIR(mode):
raise ValueError("runtime contains a special file: " + str(entry))
def normalize_tar_entry(entry):
# Stable metadata makes identical runtime contents produce identical bytes;
# executable bits and relative symlinks still survive installation.
entry.uid = entry.gid = 0
entry.uname = entry.gname = ""
entry.mtime = 0
entry.mode = 0o755 if entry.isdir() or (entry.isfile() and entry.mode & 0o111) else 0o644
if entry.issym():
entry.mode = 0o777
entry.pax_headers = {}
return entry
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("prefix", type=Path)
parser.add_argument("output", type=Path)
parser.add_argument("--arch")
args = parser.parse_args()
if sys.platform != "linux":
raise ValueError("this builder currently supports native Linux runtimes only")
prefix = args.prefix.resolve()
output = args.output.resolve()
if not prefix.is_dir():
raise ValueError("runtime directory not found: " + str(prefix))
if output == prefix or prefix in output.parents:
raise ValueError("runtime output directory must not be inside the runtime tree")
check_portable_tree(prefix)
output.mkdir(parents=True, exist_ok=True)
# Snapshot first: the archived files, version probes, and manifest must all
# refer to the same tree, even if the original prefix is rebuilt afterwards.
print("Snapshotting runtime: " + str(prefix), flush=True)
with tempfile.TemporaryDirectory(prefix=".runtime-archive-", dir=str(output)) as temporary:
stage = Path(temporary)
snapshot = stage / "runtime"
shutil.copytree(str(prefix), str(snapshot), symlinks=True,
ignore=shutil.ignore_patterns(".gitkeep"))
check_portable_tree(snapshot)
validator = Path(__file__).resolve().parent / "validate-runtime.sh"
command = ["bash", str(validator), str(snapshot)]
if args.arch:
command.extend(("--arch", args.arch))
subprocess.run(command, check=True)
manifest = json.loads((snapshot / "runtime-manifest.json").read_text())
print("Compressing validated runtime: " + manifest["runtimeId"], flush=True)
release = stage / "release"
release.mkdir(mode=0o755)
archive_path = release / "runtime.tar.gz"
with archive_path.open("wb") as raw:
with gzip.GzipFile(filename="", fileobj=raw, mode="wb", compresslevel=6, mtime=0) as compressed:
with tarfile.open(fileobj=compressed, mode="w", format=tarfile.PAX_FORMAT) as archive:
archive.add(str(snapshot), arcname="runtime", recursive=False, filter=normalize_tar_entry)
for directory, directories, files in os.walk(str(snapshot), followlinks=False):
directories.sort()
for name in sorted(directories + files):
entry = Path(directory) / name
relative = entry.relative_to(snapshot).as_posix()
archive.add(str(entry), arcname="runtime/" + relative,
recursive=False, filter=normalize_tar_entry)
checksum = file_sha256(archive_path)
name = "musrflow-runtime-{}-{}-{}".format(manifest["platform"], manifest["arch"], checksum[:16])
filename = name + ".tar.gz"
archive_path.rename(release / filename)
descriptor = {
"schemaVersion": 1,
"kind": "musrflow-runtime-download",
"runtime": manifest,
"artifact": {"filename": filename, "format": "tar.gz", "rootDirectory": "runtime",
"size": (release / filename).stat().st_size, "sha256": checksum},
}
(release / "runtime-download.json").write_text(json.dumps(descriptor, indent=2, sort_keys=True) + "\n")
(release / (filename + ".sha256")).write_text(checksum + " " + filename + "\n")
# Publish the complete directory at once. Content-addressed bundles may
# be reused, but a conflicting previous release is never overwritten.
destination = output / name
if destination.exists() or destination.is_symlink():
if destination.is_symlink() or not destination.is_dir():
raise ValueError("runtime download destination is not a regular directory: " + str(destination))
for member in release.iterdir():
existing = destination / member.name
if existing.is_symlink() or not existing.is_file() or file_sha256(existing) != file_sha256(member):
raise ValueError("existing runtime download bundle has different contents: " + str(destination))
print("Reusing runtime download: " + str(destination))
else:
release.rename(destination)
print("Built runtime download: " + str(destination))
print("Archive size: {} bytes; SHA-256: {}".format(descriptor["artifact"]["size"], checksum))
if __name__ == "__main__":
try:
main()
except (OSError, ValueError, RuntimeError, subprocess.SubprocessError, tarfile.TarError) as error:
print("ERROR: " + str(error), file=sys.stderr)
sys.exit(1)