LayMesh文档
EN

release/README.en.md

release/README.en.md
# Build and publish to PyPI The **0.8.2** release adds object selection, named anchor inspection, and source navigation to the VS Code preview. Python, Rust, runtime and extension versions stay aligned. See the [bilingual release notes](notes/0.8.2.md) and [release workflow](https://github.com/muxkin/LayMesh/actions/workflows/publish-pypi.yml). NumPy, pandas, Matplotlib and IPython are default dependencies; `pip install laymesh` installs all Python features. Check [PyPI](https://pypi.org/project/laymesh/) for the published version. The [publishing workflow](https://github.com/muxkin/LayMesh/actions/workflows/publish-pypi.yml) builds and verifies five platform wheels, audits contents and checksums, and uploads through Trusted Publishing after approval. Each wheel includes the Python API, CLI entry point, one native Rust executable, dependency licenses and a build manifest. Formula fonts are compiled into RaTeX; body fonts come from the system or user files. [runtime.json](runtime.json) defines five targets: Linux x64 / arm64, macOS 14+ Intel / Apple Silicon, and Windows x64. Python users need 3.10+; build scripts need Python 3.11+ and Rust 1.93.1. This release publishes platform wheels only. The `python/` directory alone is not a complete source distribution with the Rust engine; do not upload an sdist made from that directory. Release checks reject mismatched Python, Rust, runtime and extension versions. The workflow also builds VSIX packages for all five platforms and audits their native architectures; each extension's native binary must match the corresponding wheel's hash. Publication checks require all five PyPI files to match the original reviewed SHA-256 hashes. ## Local build and audit Use a virtual environment, install the pinned tooling, and run from the repository root: ```shpython -m pip install -r release/build-requirements.txtpython scripts/check-release.pypython -m pip install -e "./python" pillowpython scripts/test-contracts.pypython scripts/collect-licenses.pypython scripts/build-python-wheel.py --output release/dist/pypi-0.8.2python scripts/check-python-wheels.py release/dist/pypi-0.8.2 --checksums release/dist/pypi-0.8.2/SHA256SUMSpython -m twine check --strict release/dist/pypi-0.8.2/*.whl``` The builder checks version alignment, compiles the locked release engine, and stages a wheel outside the source tree. A separate output directory avoids mixing this candidate with earlier wheels. Linux tags reflect the binary's measured GLIBC symbol requirements, with a floor of 2.28; a newer host build must not claim an older baseline. The local Linux x64 wheel requires glibc 2.39+. CI runner builds may require a newer glibc; review the actual filenames and manifests. The manifest records Python/Rust versions, target, executable SHA-256 and Cargo.lock SHA-256. The audit checks metadata, platform tags, executable permissions, hashes, license texts and absence of local home paths. It rejects Node/npm, JS runtime files and body-font bundles. Recollect licenses whenever locked dependencies change; CI does this for every build. ## Verify the installed wheel Create a **second, clean virtual environment** and install the generated wheel, not an editable checkout. Replace the example filename below with the actual wheel for your machine: ```shpython -m pip install "release/dist/pypi-0.8.2/laymesh-0.8.2-py3-none-manylinux_2_39_x86_64.whl" pillowpython -m pip checkpython -m laymesh --versionpython scripts/smoke-python-wheel.py --examples examplespython -m unittest discover -s python/tests -vpython -m pip install -r release/jupyter-requirements.txtpython scripts/test-python-jupyter.py --installed --output release/verification/jupyter``` The smoke test changes into a temporary directory and empties PATH. It checks SVG/PDF/PNG/JPEG/TIFF/WebP exports, CLI and module entry points, saved data, Matplotlib import, both Notebook magics and standalone example entry points using the bundled engine. Local checks certify only the tested platform. The workflow builds five platforms on Python 3.13 and installs the resulting wheels on Python 3.10 and 3.14 as well. Linux source builds require `pkg-config`, `libfontconfig1-dev`, `libfreetype-dev`, `libbrotli-dev`, `libbz2-dev`, `libexpat1-dev`, `libpng-dev` and `zlib1g-dev` (Debian/Ubuntu package names). The native engine links these font/codec helpers statically; wheel and VSIX audits reject unbundled optional Linux libraries. Their distribution copyright notices accompany the binary. Installed packages do not require a GPU or these development packages. ## GitHub and PyPI setup The existing [publish workflow](../.github/workflows/publish-pypi.yml) uses [PyPA's Trusted Publishing procedure](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/). Before the first upload: 1. Configure a PyPI pending trusted publisher with project `laymesh`, owner `muxkin`, repository `LayMesh`, workflow `publish-pypi.yml`, and environment `pypi`.2. Configure the repository's GitHub environment `pypi` with required reviewers. The workflow checks that this approval gate exists.3. Push the verified commit to `main`, then create and push the stable tag: `git tag v0.8.2` and `git push origin v0.8.2`.4. Review the wheels, VSIX and checksums from this run, then approve the `pypi` environment. Successful upload automatically creates the GitHub Release. The publishing job downloads the exact reviewed artifacts and uploads them without rebuilding. Pull requests and ordinary build runs do not upload. After publication, verify an index installation outside the checkout with `python -m pip install "laymesh==0.8.2"`, then `python -m pip check` and `python -m laymesh --version`. A published version cannot be overwritten; increment the Python/Rust/runtime/VS Code extension versions together for a replacement release. ## Verification records `python scripts/test-contracts.py` produces `release/verification/cargo-tests.log`, `python-tests.log` and `assertion-coverage.json`, checking current source identities, test execution and historical assertion mappings. Install the Poppler and MuPDF command-line tools before running these checks. Use the GitHub Actions runs for the current commit as cross-platform release evidence; the final wheels and checksums are stored in the `reviewed-python-release` artifact. ## Manual VS Code publishing and GitHub Release Stable version tags trigger five-platform wheel/VSIX builds and audits. The existing PyPI environment approval remains. Successful PyPI upload creates a GitHub Release with bilingual notes, ten reviewed packages and SHA256SUMS. Tags must match all metadata and belong to main. PR and manual workflow runs validate without uploading. Marketplace automation has been removed. Download the VSIX packages from the Release and upload them through the [Hyacine publisher portal](https://marketplace.visualstudio.com/manage/publishers/Hyacine), or use local `vsce publish --packagePath <reviewed.vsix>`. Credentials stay local. `scripts/marketplace-release.py audit` remains available for package audits. Release retries verify hashes and refuse to overwrite different content; notes live in `release/notes/<version>.md`. Retry only failed publication jobs in the original run (`gh run rerun <run-id> --failed`), so they download the same reviewed artifacts. Do not rebuild and substitute packages for an already uploaded version. ## Other artifacts Build the native VS Code extension with `python scripts/build-editors.py`, package it with `python scripts/package-editor.py --output release/dist/laymesh.vsix`, and audit with `python scripts/check-editor.py release/dist/laymesh.vsix`. Build the Rust/WASM documentation site with `python scripts/build-docs.py`. The publishing workflow also produces VSIX packages for all five platforms, sharing their version with Python and the engine. VSIX files are distributed separately from the PyPI wheel. When Rust sources, Cargo versions or the lockfile change, regenerate documentation media with the current engine: `python scripts/build-docs-media.py --binary target/release/laymesh`, then run `python scripts/build-docs.py` and `python scripts/build-docs.py --check`. Commit the regenerated `site/media` images and manifest; documentation CI rejects cached media whose renderer fingerprint no longer matches.