pheon/docs/releases.md
Jan Petykiewicz f474e9848c Require PyArrow in the Python package
Keep the arrow extra available for existing requirements. Update wheel checks and install instructions, and verify that integer packing leaves PyArrow unloaded.
2026-11-18 12:36:58 -08:00

107 lines
4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Building releases
Build packages locally for distribution. For installing and using Pheon, start
with the [CLI](cli.md) or [Python](python.md) guide.
## 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.
```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install build twine
python -m build --sdist --outdir dist/release
```
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.
```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
```
cibuildwheel repairs the wheel and tests the same file on Python 3.11–3.14.
The container downloads any Python dependencies that it needs.
## Build Windows x86-64 packages from Linux
Install MinGW-w64 with `x86_64-w64-mingw32-gcc` on `PATH`. From the project
environment, build the Windows wheel and the standalone CLI:
```sh
rustup target add x86_64-pc-windows-gnu
PHEON_BUILD_TARGET=x86_64-pc-windows-gnu python -m build --wheel --outdir dist/release
cargo build --locked --release --target x86_64-pc-windows-gnu --bin pheon
```
The `py3-none-win_amd64` wheel lands in `dist/release/`. The executable is
`target/x86_64-pc-windows-gnu/release/pheon.exe`. Test the wheel and CLI on Windows
before publishing.
## Validate artifacts
Check the Python package metadata and verify that the packaged crate builds.
```sh
python -m twine check --strict dist/release/*.tar.gz dist/release/*.whl
cargo publish --dry-run --locked
```
Wheel filenames use `py3-none` plus a platform tag, such as
`manylinux_2_28_x86_64` or `win_amd64`. Use repaired `manylinux_*` wheels for
Linux releases.
To test a wheel manually, install it in a test environment on the target OS.
Clear `PHEON_LIBRARY` so the checks load the bundled library. Replace the
example path with the wheel you built.
```sh
python -m pip install "path/to/pheon-wheel.whl"
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.