diff --git a/docs/releases.md b/docs/releases.md index b21c70d..c36c7ba 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,16 +1,18 @@ # Building releases -Build packages locally for distribution. For installing and using Pheon, start -with the [CLI](cli.md) or [Python](python.md) guide. +Build packages locally for distribution. The checkout holds Python build tools +in `.venv/`, release artifacts in `dist/release/`, and Linux wheel caches in +`.cache/wheels/`. Use your installed Rust toolchain and Cargo registry cache. ## Start a release -Use Python 3.11+ and Rust 1.88+. From the repository root, create a build -environment and put the source archive in an empty `dist/release/` directory. +Use Python 3.11+ and Rust 1.88+. Run the commands from the repository root and +start with an empty `dist/release/` directory. ```sh python3 -m venv .venv . .venv/bin/activate +export PIP_CACHE_DIR="$PWD/.cache/wheels/pip" python -m pip install build twine python -m build --sdist --outdir dist/release ``` @@ -19,50 +21,28 @@ Use `python -m build --wheel` to build a wheel for your own machine. For a portable Linux wheel, use the container below. See [development](development.md) for compiler checks. -Python wheels bundle the native library. Install the CLI separately with Cargo. - ## Build Linux x86-64 wheels -On x86-64 Linux, use Podman and a Rust toolchain installed through `rustup`. -Download the [pinned manylinux image](../contrib/wheels/manylinux-image.txt) -once and save it for future releases. - -```sh -pheon_wheel_cache="$PWD/.cache/wheels" -pheon_image=$(cat contrib/wheels/manylinux-image.txt) -pheon_cached_image=localhost/pheon-manylinux:2.28-2026.10.26-1 -mkdir -p "$pheon_wheel_cache" -podman pull --platform linux/amd64 "$pheon_image" -podman tag "$pheon_image" "$pheon_cached_image" -podman save --format oci-archive \ - --output "$pheon_wheel_cache/manylinux_2_28_x86_64.oci.tar" \ - "$pheon_cached_image" -``` - -If the image is missing from Podman, restore it with -`podman load --input .cache/wheels/manylinux_2_28_x86_64.oci.tar`. -Build from the source archive using the local Rust toolchain and Cargo cache. +On x86-64 Linux, use rootless Podman and a Rust toolchain installed through +`rustup`. Build the portable wheel from the source archive. ```sh python -m pip install 'cibuildwheel==4.3.5' -cargo fetch --locked --target x86_64-unknown-linux-gnu -rust_toolchain=$(rustc --print sysroot) -cargo_registry="${CARGO_HOME:-$HOME/.cargo}/registry" -export CIBW_CONTAINER_ENGINE="podman; disable_host_mount: true; create_args: \ - --volume '$PWD/.cache/wheels:/pheon-cache' \ - --volume '$rust_toolchain:/rust-toolchain:ro' \ - --volume '$cargo_registry:/pheon-cache/cargo/registry:ro'" -export CIBW_MANYLINUX_X86_64_IMAGE=localhost/pheon-manylinux:2.28-2026.10.26-1 -export CIBW_ENVIRONMENT_LINUX='PATH=/rust-toolchain/bin:$PATH CARGO_HOME=/pheon-cache/cargo CARGO_NET_OFFLINE=true PIP_CACHE_DIR=/pheon-cache/pip' -export CIBW_BUILD='cp31{1,2,3,4}-manylinux_x86_64' -export CIBW_TEST_COMMAND='python -I {project}/tools/check_installed.py' -unset PHEON_LIBRARY -python -m cibuildwheel --platform linux --archs x86_64 \ - --output-dir dist/release dist/release/pheon-*.tar.gz +python tools/build_manylinux.py dist/release/pheon-*.tar.gz ``` -cibuildwheel repairs the wheel and tests the same file on Python 3.11–3.14. -The container downloads any Python dependencies that it needs. +The helper pulls the [pinned image](../contrib/wheels/manylinux-image.txt) when +needed and reuses it from `.cache/wheels/podman/storage/`. It keeps Podman’s +storage runtime directory, download scratch space, and wheel caches under +`.cache/wheels/`. Podman still uses the normal system user runtime for host +services. To inspect this checkout’s images, use the same helper. + +```sh +python tools/build_manylinux.py podman image ls +``` + +cibuildwheel repairs the wheel and tests it on Python 3.11–3.14. The container +uses the host Rust toolchain and Cargo registry through read-only mounts. ## Build Windows x86-64 packages from Linux @@ -104,4 +84,12 @@ python -I tools/check_installed.py Build standalone CLI artifacts for each OS and architecture. Include the executable, license, README, documentation, and Git templates. -Publish the validated Python packages to PyPI and the Rust crate to crates.io. +## Publish + +Upload the validated Python files you selected, then publish the crate from a +clean release checkout. + +```sh +python -m twine upload --repository pypi FILE ... +cargo publish --locked +``` diff --git a/tools/build_manylinux.py b/tools/build_manylinux.py new file mode 100644 index 0000000..c90c7da --- /dev/null +++ b/tools/build_manylinux.py @@ -0,0 +1,104 @@ +"""Build Linux release wheels using Podman storage in this checkout.""" + +import argparse +import json +import os +from pathlib import Path +import shlex +import subprocess +import sys + + +ROOT = Path(__file__).resolve().parents[1] +CACHE = ROOT / ".cache/wheels" + + +def local_environment() -> dict[str, str]: + podman = CACHE / "podman" + scratch = CACHE / "tmp" + podman.mkdir(parents=True, exist_ok=True) + scratch.mkdir(exist_ok=True) + storage = podman / "storage.conf" + graphroot = json.dumps(str(podman / "storage"), ensure_ascii=False) + runroot = json.dumps(str(podman / "run"), ensure_ascii=False) + config = f"[storage]\ngraphroot = {graphroot}\nrunroot = {runroot}\n" + # Replace the config atomically so simultaneous Podman commands can read it. + if not storage.exists() or storage.read_text(encoding="utf-8") != config: + temporary = podman / f"storage.{os.getpid()}.conf" + temporary.write_text(config, encoding="utf-8") + temporary.replace(storage) + + env = dict(os.environ, CONTAINERS_STORAGE_CONF=str(storage), TMPDIR=str(scratch)) + for key in ("CONTAINER_HOST", "CONTAINER_CONNECTION"): + env.pop(key, None) + return env + + +def build(sdist: Path) -> None: + env = local_environment() + image = (ROOT / "contrib/wheels/manylinux-image.txt").read_text(encoding="utf-8").strip() + + # Use the same Podman invocation as cibuildwheel to check the active store. + graphroot = subprocess.check_output( + ["podman", "info", "--format", "{{.Store.GraphRoot}}"], env=env, text=True, + ).strip() + if Path(graphroot).resolve() != (CACHE / "podman/storage").resolve(): + raise SystemExit(f"Expected the checkout's Podman store, found {graphroot}") + + subprocess.run( + ["cargo", "fetch", "--locked", "--target", "x86_64-unknown-linux-gnu"], + cwd=ROOT, env=env, check=True, + ) + toolchain = subprocess.check_output( + ["rustc", "--print", "sysroot"], cwd=ROOT, env=env, text=True, + ).strip() + registry = Path(env.get("CARGO_HOME", Path.home() / ".cargo")).resolve() / "registry" + for directory in ("cargo/registry", "pip", "target", "cibuildwheel"): + (CACHE / directory).mkdir(parents=True, exist_ok=True) + mounts = [ + f"{toolchain}:/rust-toolchain:ro", + f"{CACHE / 'cargo'}:/pheon-cache/cargo", + f"{registry}:/pheon-cache/cargo/registry:ro", + f"{CACHE / 'pip'}:/pheon-cache/pip", + f"{CACHE / 'target'}:/pheon-cache/target", + ] + create_args = shlex.join([arg for mount in mounts for arg in ("--volume", mount)]) + env.update( + CIBW_CONTAINER_ENGINE=f"podman; disable_host_mount: true; create_args: {create_args}", + CIBW_MANYLINUX_X86_64_IMAGE=image, + CIBW_ENVIRONMENT_LINUX=( + "PATH=/rust-toolchain/bin:$PATH CARGO_HOME=/pheon-cache/cargo " + "CARGO_TARGET_DIR=/pheon-cache/target CARGO_NET_OFFLINE=true " + "PIP_CACHE_DIR=/pheon-cache/pip" + ), + CIBW_CACHE_PATH=str(CACHE / "cibuildwheel"), + CIBW_BUILD="cp31{1,2,3,4}-manylinux_x86_64", + CIBW_TEST_COMMAND="python -I {project}/tools/check_installed.py", + ) + env.pop("PHEON_LIBRARY", None) + subprocess.run( + [sys.executable, "-m", "cibuildwheel", "--platform", "linux", "--archs", "x86_64", + "--output-dir", str(sdist.parent), str(sdist)], + cwd=ROOT, env=env, check=True, + ) + + +def main() -> int: + if sys.argv[1:2] == ["podman"]: + return subprocess.run( + ["podman", "--remote=false", *sys.argv[2:]], env=local_environment(), + ).returncode + + parser = argparse.ArgumentParser( + description=__doc__, epilog="Use 'podman ARGS' to inspect the local store.", + ) + parser.add_argument("sdist", type=Path, help="Pheon source archive") + args = parser.parse_args() + if not args.sdist.is_file(): + parser.error(f"source archive does not exist: {args.sdist}") + build(args.sdist.resolve()) + return 0 + + +if __name__ == "__main__": + sys.exit(main())