pheon/docs/releases.md

95 lines
3.1 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. 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
```