Skip to content

livery-extensions-nanobind

A python package whose extension module is C++, bound to python through nanobind, built into one wheel per platform. A package turns it on by listing the extension in its own workshop.toml:

extensions = ["nanobind"]
name = "acme-native"

[nanobind]
wheel-platforms = ["ubuntu-latest", "macos-latest", "windows-latest"]

nanobind requires python for the distribution, cpp for the extension module's sources, and conan for the provider that resolves their C++ dependencies, so a package that lists nanobind holds all four. The package consumes conan's packages without being a conan package: its recipe names the requirements its extension module builds against, and no version.

A new package

fm new.package.nanobind-module <name> creates such a package while the workspace lists nanobind: the python library's seeds, then the extension module's sources, its CMake build, its pyproject.toml with scikit-build-core as the build backend, and the conan recipe that names fmt as its one requirement. The template takes no --command. A workspace that does not list nanobind has no such verb: list the extension in [workspace] extensions and run fm sync, which installs livery-extensions-nanobind, and the verb exists.

The build

The release train builds a package that holds nanobind on the build phase's isolated side. cibuildwheel builds and repairs each platform wheel, so even one host's wheel is manylinux-compliant on Linux, and uv build writes the sdist. Every build resolves the extension module's C++ dependencies through the cmake-conan provider and conan from the store. On Linux cibuildwheel builds in a container, which mounts the workspace, the store, the provider and the conan home at their host paths, and installs conan at the store's version for itself, since the store's binary is linked against the host's C library. A build refuses a wheel tagged none-any: such a wheel was built without its extension module.

The steps of python and conan that would stamp, build or release something else are deleted in every package whose set holds nanobind, each with its reason. The release's stamp is nanobind's own: it writes the version into pyproject.toml and every __version__ and raises the pyproject's floors through python, and raises the recipe's floors through conan, since one step of a package reports the files the stamp changed. nanobind answers the version-files query with the recipe, the one file the step writes beyond python's, so the release keeps and restores it, and the local act refuses while it has changes of its own:

[phases.stamp.nanobind]
main = "livery.extensions.nanobind._stamp:stamp"
reads = ["version", "floors"]
provides = { changed = "strs" }

[phases.stamp.nanobind.deletes]
"python:stamp.python" = "this step writes the version and the pyproject's floors through python's stamp, and raises the recipe's floors too"
"conan:stamp.conan" = "the package's recipe names the requirements its extension module builds against and no version, and this step raises its floors through conan"

[phases.build.nanobind]
main = "livery.extensions.nanobind._build:build"
isolated = true
reads = ["epoch"]
provides = { dist = "path" }

[phases.build.nanobind.deletes]
"python:build.python" = "uv build writes a pure wheel, and the package's wheels are platform wheels, which this step builds with the sdist"
"conan:build.conan" = "the package's recipe creates no conan package: the provider installs its requirements while the wheels build"
"conan:publish.conan" = "the package releases its wheels, never a conan package"

A package whose set does not hold nanobind runs those steps as before. The build runs cmake, ninja, conan and the cmake-conan provider, which the lock pins while a package's set holds nanobind. nanobind itself and scikit-build-core arrive through the package's own build-system requires. The venv carries nanobind too, so an editor's configure of the extension module finds nanobind's cmake directory.

The wheels job

A package that holds nanobind names the runner labels that build its platform wheels under [nanobind] wheel-platforms. The key is required there, must be a non-empty list of labels, and refuses in a package that holds no nanobind. The extension adds a wheels job to the release workflow: before the wave, one leg per label in the union over those packages builds that platform's wheels for the workspace's python matrix, and the publish job waits for the legs and ships the collected set. A workspace whose packages hold no nanobind has no wheels job.

Each leg runs fm nanobind.wheels at the release squash the wave publishes. A leg builds every member of the release that the workspace's job-built-members answer names. nanobind answers it with every package that holds nanobind and every package that releases a conan package. A release with no such member builds nothing and says so, so the leg stays green on a pure release.

A leg builds the packages the release ships, so it sets the workspace's conanws.yml aside while it builds: a member's conan create and a nanobind package's wheel resolve a sibling to the package the leg created, never to its source tree. The file comes back when the builds end, a failure included. The leg creates each conan package first and saves its cache as dist/<name>-<version>-<host>.tgz, then builds the wheels, which resolve the library from the leg's own cache.

Every floor a member declares on a conan member is proved in the leg that builds it: the floor's cache is restored from its own release, one wheel is built for that machine with a conan profile replacing the requirement with the floor, and the package's tests run against it. A floor equal to the version the wave is releasing is the package the main build already linked, and the leg says so instead of building twice.

In CI the wave publishes what the run collected into those members' dist/; a job-built member whose dist/ holds nothing refuses the wave, naming the job.