pheon/docs/releases.md

95 lines
3.1 KiB
Markdown
Raw Permalink Normal View History

# 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
```