0
# setuptools-rust
1

2
A setuptools plugin that provides seamless integration of Rust code into Python projects. It enables developers to build Python extensions written in Rust using PyO3 or rust-cpython bindings, compiling and distributing them as easily as C extensions.
3

4
## Package Information
5

6
- **Package Name**: setuptools-rust
7
- **Package Type**: Python (setuptools plugin)
8
- **Language**: Python
9
- **Installation**: `pip install setuptools-rust`
10

11
## Core Imports
12

13
```python
14
from setuptools_rust import RustExtension, RustBin, Binding, Strip
15
```
16

17
For distutils commands:
18

19
```python
20
from setuptools_rust import build_rust, clean_rust
21
```
22

23
## Basic Usage
24

25
### Using setup.py
26

27
```python
28
from setuptools import setup
29
from setuptools_rust import RustExtension
30

31
setup(
32
    name="my-rust-extension",
33
    version="0.1.0",
34
    rust_extensions=[
35
        RustExtension(
36
            "my_extension.rust_module",  # Python module name
37
            path="Cargo.toml",           # Path to Cargo.toml
38
            binding=Binding.PyO3,        # Binding type
39
        )
40
    ],
41
    zip_safe=False,  # Rust extensions are not zip safe
42
)
43
```
44

45
### Using pyproject.toml
46

47
```toml
48
[build-system]
49
requires = ["setuptools", "setuptools-rust"]
50

51
[[tool.setuptools-rust.ext-modules]]
52
target = "my_extension.rust_module"
53
path = "Cargo.toml"
54
binding = "PyO3"
55

56
[[tool.setuptools-rust.bins]]
57
target = "my-binary"
58
path = "Cargo.toml"
59
```
60

61
## Architecture
62

63
setuptools-rust integrates with the Python packaging ecosystem through multiple layers:
64

65
- **Extension Configuration**: `RustExtension` and `RustBin` classes define build targets and options
66
- **Build Commands**: `build_rust` and `clean_rust` commands handle the Cargo build process
67
- **setuptools Integration**: Entry points and hooks automatically integrate Rust building into standard Python packaging workflows
68
- **Cross-compilation Support**: Full support for building across different target platforms
69

70
## Capabilities
71

72
### Extension Building
73

74
Configure and build Rust extensions as Python modules or standalone binaries. Supports multiple binding types (PyO3, rust-cpython, custom), cross-compilation, and extensive build customization.
75

76
```python { .api }
77
class RustExtension:
78
    def __init__(
79
        self,
80
        target: Union[str, Dict[str, str]],
81
        path: str = "Cargo.toml",
82
        binding: Binding = Binding.PyO3,
83
        **kwargs
84
    ): ...
85

86
class RustBin(RustExtension):
87
    def __init__(
88
        self,
89
        target: Union[str, Dict[str, str]],
90
        path: str = "Cargo.toml",
91
        **kwargs
92
    ): ...
93

94
class Binding(IntEnum):
95
    PyO3 = auto()
96
    RustCPython = auto()
97
    NoBinding = auto()
98
    Exec = auto()
99

100
class Strip(IntEnum):
101
    No = auto()
102
    Debug = auto()
103
    All = auto()
104
```
105

106
[Extension Building](./extension-building.md)
107

108
### Build Commands
109

110
Distutils commands for building and cleaning Rust extensions, with integration into standard Python packaging workflows.
111

112
```python { .api }
113
class build_rust(RustCommand):
114
    description = "build Rust extensions (compile/link to build directory)"
115
    
116
    def run_for_extension(self, ext: RustExtension) -> None: ...
117
    def build_extension(
118
        self, 
119
        ext: RustExtension, 
120
        forced_target_triple: Optional[str] = None
121
    ) -> List[_BuiltModule]: ...
122

123
class clean_rust(RustCommand):
124
    description = "clean Rust extensions"
125
    
126
    def run_for_extension(self, ext: RustExtension) -> None: ...
127
```
128

129
[Build Commands](./commands.md)
130

131
### Configuration Options
132

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

135
```toml { .api }
136
[[tool.setuptools-rust.ext-modules]]
137
target = "module_name"
138
path = "Cargo.toml"
139
binding = "PyO3"
140
features = ["feature1", "feature2"]
141
debug = false
142

143
[[tool.setuptools-rust.bins]]
144
target = "binary_name"
145
path = "Cargo.toml"
146
strip = "Debug"
147
```
148

149
[Configuration](./configuration.md)
150

151
## Types
152

153
```python { .api }
154
from typing import Union, Dict, List, Optional, Sequence, Literal
155
from enum import IntEnum, auto
156

157
CargoMetadata = NewType("CargoMetadata", Dict[str, Any])
158

159
class Env:
160
    """Hashable wrapper for environment variable dictionaries."""
161

162
class SimpleSpec:
163
    """Parsed Rust version requirement specification."""
164
```
165

166
## Environment Variables
167

168
Key environment variables that control the build process:
169

170
- `SETUPTOOLS_RUST_CARGO_PROFILE`: Override cargo profile (e.g., "release", "dev")
171
- `CARGO_BUILD_TARGET`: Set build target triple for cross-compilation
172
- `CARGO`: Path to cargo executable
173
- `RUSTFLAGS`: Additional flags passed to rustc compiler