108 lines
4 KiB
Markdown
108 lines
4 KiB
Markdown
# 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_EXTRAS=arrow
|
||
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 with its `arrow` extra 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[arrow]"
|
||
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.
|