maturin-pants-plugin

A Pantsbuild plugin for building and publishing Rust-backed Python wheels with maturin.

Status: alpha. pants package and pants publish work for maturin_wheel targets; only *.whl outputs are supported.

Installation

Add the plugin to pants.toml. The plugin needs the Python backend too:

[GLOBAL]
plugins = ["maturin-pants-plugin==<version>"]
backend_packages.add = ["pants.backend.python"]

cargo, rustc and the interpreters listed in [maturin].interpreter MUST be on the PATH of the shell that runs Pants: the plugin passes PATH, HOME, CARGO_HOME and RUSTUP_HOME into the build sandbox.

Usage

Declare a maturin_wheel target in the directory holding the crate's Cargo.toml and pyproject.toml:

maturin_wheel(
    name="wheel",
    # Files `maturin build` needs that are not matched by the default `sources` globs.
    dependencies=[":readme", "python/my_pkg"],
    # Registries for `pants publish`. `@name` is a `.pypirc` section, anything else a `--repository-url`.
    repositories=["@pypi"],
)

file(name="readme", source="README.md")

By default sources covers Cargo.toml, Cargo.lock, pyproject.toml, build.rs, src/**/*.rs, tests/**/*.rs and python/**. cargo_toml and pyproject_toml default to the files of those names next to the BUILD file; both MUST be matched by sources, and pyproject.toml MUST sit beside Cargo.toml.

pants package path/to/crate:wheel   # runs `maturin build`, writes dist/<name>-<version>-<tags>.whl
pants publish path/to/crate:wheel   # runs `maturin upload` once per entry of `repositories`

maturin upload reads credentials from MATURIN_PYPI_TOKEN, or MATURIN_USERNAME and MATURIN_PASSWORD, or your ~/.pypirc. Targets without repositories, or with skip_maturin_upload=True, are skipped by pants publish without being built.

Options

Configure the [maturin] section of pants.toml. Run pants help-advanced maturin for the full list.

Cargo's target/ directory lives in a Pants named cache, so repeated builds are incremental.

Regenerating the tool lockfile

The plugin ships a lockfile for the maturin tool itself. It is generated through the maturin resolve declared in the repo's pants.toml and the maturin-tool requirement in provides/maturin-pants-plugin/BUILD:

pants generate-lockfiles --resolve=maturin

Supported versions

Pants loads plugins into its own interpreter, so the plugin requires the Python version Pants runs on.

Releases

Wheels are published to PyPI. Release notes live in the changelog and on the GitHub releases page.

Contributing, Bug Reports and Feature Requests

This plugin lives in the pants-plugin-depot repo. See its CONTRIBUTING.md, or open an issue.