tessl/pypi-setuptools-rust

Setuptools Rust extension plugin

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/pypi-setuptools-rust
Author: tessl

Comprehensive configuration through pyproject.toml files and setuptools integration, supporting extension modules and binaries with full control over build options, features, and environment variables.

Capabilities

pyproject.toml Configuration

Configure Rust extensions and binaries directly in pyproject.toml using the tool.setuptools-rust section.

Extension Module Configuration

[[tool.setuptools-rust.ext-modules]]
target = "module_name"              # Required: Python module name
path = "Cargo.toml"                 # Path to Cargo.toml (default: "Cargo.toml")
args = ["--arg1", "--arg2"]         # Extra cargo build arguments
cargo-manifest-args = ["--locked"]  # Cargo manifest arguments
features = ["feature1", "feature2"] # Cargo features to enable
rustc-flags = ["-C", "opt-level=3"] # Additional rustc flags
rust-version = "1.65.0"             # Minimum Rust version
quiet = false                       # Suppress cargo output
debug = false                       # Debug build (overrides release)
binding = "PyO3"                    # Binding type: "PyO3", "RustCPython", "NoBinding", "Exec"
strip = "No"                        # Symbol stripping: "No", "Debug", "All"
script = false                      # Install as console script
native = false                      # Use native target
optional = false                    # Optional build (failure won't stop installation)
py-limited-api = "auto"             # Python limited API: "auto", true, false

[tool.setuptools-rust.ext-modules.env]
VAR1 = "value1"                     # Environment variables for build
VAR2 = "value2"

Binary Configuration

[[tool.setuptools-rust.bins]]
target = "binary_name"              # Required: Binary name
path = "Cargo.toml"                 # Path to Cargo.toml
args = ["--release"]                # Extra cargo build arguments
cargo-manifest-args = []            # Cargo manifest arguments
features = []                       # Cargo features to enable
rust-version = "1.65.0"             # Minimum Rust version
quiet = false                       # Suppress cargo output
debug = false                       # Debug build
strip = "Debug"                     # Symbol stripping
optional = false                    # Optional build

[tool.setuptools-rust.bins.env]
CUSTOM_VAR = "value"                # Environment variables for build

setuptools Integration

Functions that integrate setuptools-rust with the Python packaging system through entry points and hooks.

def rust_extensions(
    dist: Distribution, 
    attr: Literal["rust_extensions"], 
    value: List[RustExtension]
) -> None:
    """
    Setup keyword handler for rust_extensions.

    Parameters:
    - dist: Distribution instance
    - attr: Attribute name (always "rust_extensions")
    - value: List of RustExtension instances
    """

def pyprojecttoml_config(dist: Distribution) -> None:
    """
    Load and apply pyproject.toml configuration for setuptools-rust.

    Parameters:
    - dist: Distribution instance to configure
    """

def add_rust_extension(dist: Distribution) -> None:
    """
    Add Rust extension support to a distribution.

    Parameters:
    - dist: Distribution instance to enhance
    """

Entry Points

setuptools-rust registers entry points that integrate with the Python packaging system:

Distutils Commands

# Entry points for distutils commands
build_rust = "setuptools_rust:build_rust"
clean_rust = "setuptools_rust:clean_rust"

Setup Keywords

# Entry point for setup() keyword arguments
rust_extensions = "setuptools_rust.setuptools_ext:rust_extensions"

Distribution Finalization

# Entry point for pyproject.toml integration
setuptools_rust = "setuptools_rust.setuptools_ext:pyprojecttoml_config"

Configuration Examples

Basic Extension Setup

[build-system]
requires = ["setuptools", "setuptools-rust"]
build-backend = "setuptools.build_meta"

[project]
name = "my-rust-extension"
version = "0.1.0"

[[tool.setuptools-rust.ext-modules]]
target = "my_package.rust_module"
path = "rust/Cargo.toml"
binding = "PyO3"

Multiple Extensions with Different Bindings

[[tool.setuptools-rust.ext-modules]]
target = "my_package.pyo3_module"
path = "pyo3/Cargo.toml"
binding = "PyO3"
features = ["python-extension"]

[[tool.setuptools-rust.ext-modules]]
target = "my_package.cpython_module"  
path = "cpython/Cargo.toml"
binding = "RustCPython"
debug = true

Cross-compilation Configuration

[[tool.setuptools-rust.ext-modules]]
target = "my_package.cross_module"
path = "Cargo.toml"
args = ["--target", "aarch64-apple-darwin"]

[tool.setuptools-rust.ext-modules.env]
CARGO_BUILD_TARGET = "aarch64-apple-darwin"

Release Optimization

[[tool.setuptools-rust.ext-modules]]
target = "my_package.optimized"
path = "Cargo.toml"
debug = false
strip = "All"
rustc-flags = ["-C", "target-cpu=native", "-C", "opt-level=3"]
features = ["simd", "optimizations"]

Development Configuration

[[tool.setuptools-rust.ext-modules]]
target = "my_package.dev_module"
path = "Cargo.toml"
debug = true
quiet = false
rustc-flags = ["-C", "debuginfo=2"]
features = ["debugging", "profiling"]

Binary Tools

[[tool.setuptools-rust.bins]]
target = "my-cli-tool"
path = "cli/Cargo.toml"
strip = "Debug"
features = ["cli"]

[[tool.setuptools-rust.bins]]
target = "my-helper"
path = "helper/Cargo.toml"
optional = true  # Won't fail installation if build fails

Environment Variable Configuration

[[tool.setuptools-rust.ext-modules]]
target = "my_package.configured"
path = "Cargo.toml"

[tool.setuptools-rust.ext-modules.env]
RUSTFLAGS = "-C target-feature=+crt-static"
CARGO_PROFILE_RELEASE_LTO = "true"
CUSTOM_BUILD_VAR = "production"

Optional Extensions

[[tool.setuptools-rust.ext-modules]]
target = "my_package.optional_feature"
path = "optional/Cargo.toml"
optional = true
quiet = true
features = ["experimental"]

Legacy setup.py Integration

For projects still using setup.py, setuptools-rust can be configured through the rust_extensions keyword:

from setuptools import setup
from setuptools_rust import RustExtension, Binding

setup(
    name="my-package",
    version="0.1.0",
    rust_extensions=[
        RustExtension(
            "my_package.rust_module",
            path="Cargo.toml",
            binding=Binding.PyO3,
            features=["python-extension"],
            debug=False,
        )
    ],
    zip_safe=False,  # Rust extensions are not zip safe
)

Configuration Validation

setuptools-rust validates configuration at build time:

Required Fields: target must be specified for all extensions and binaries
Path Validation: Cargo.toml files must exist at specified paths
Binding Compatibility: Binding types must be valid enum values
Feature Validation: Cargo features are validated against Cargo.toml
Environment Variables: Invalid environment variable names are rejected

Build Profile Override

The cargo build profile can be overridden using environment variables:

# Override profile for all extensions
export SETUPTOOLS_RUST_CARGO_PROFILE=release

# Build with custom profile
python setup.py build_rust

Or through configuration:

[[tool.setuptools-rust.ext-modules]]
target = "my_package.module"
args = ["--profile", "custom-profile"]

Type Definitions

from typing import List, Dict, Literal, Optional
from setuptools import Distribution

# Configuration types
ConfigSection = Dict[str, Any]
ExtModuleConfig = Dict[str, Any]
BinConfig = Dict[str, Any]

Install with Tessl CLI

npx tessl i tessl/pypi-setuptools-rust

docs

commands.md

configuration.md

extension-building.md

index.md

tile.json