95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# Building releases
|
||
|
||
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+. 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
|
||
```
|
||
|
||
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.
|
||
|
||
## Build Linux x86-64 wheels
|
||
|
||
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'
|
||
python tools/build_manylinux.py dist/release/pheon-*.tar.gz
|
||
```
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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
|
||
```
|