0
# Configuration
1

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

4
## Capabilities
5

6
### pyproject.toml Configuration
7

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

10
#### Extension Module Configuration
11

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

30
[tool.setuptools-rust.ext-modules.env]
31
VAR1 = "value1"                     # Environment variables for build
32
VAR2 = "value2"
33
```
34

35
#### Binary Configuration
36

37
```toml { .api }
38
[[tool.setuptools-rust.bins]]
39
target = "binary_name"              # Required: Binary name
40
path = "Cargo.toml"                 # Path to Cargo.toml
41
args = ["--release"]                # Extra cargo build arguments
42
cargo-manifest-args = []            # Cargo manifest arguments
43
features = []                       # Cargo features to enable
44
rust-version = "1.65.0"             # Minimum Rust version
45
quiet = false                       # Suppress cargo output
46
debug = false                       # Debug build
47
strip = "Debug"                     # Symbol stripping
48
optional = false                    # Optional build
49

50
[tool.setuptools-rust.bins.env]
51
CUSTOM_VAR = "value"                # Environment variables for build
52
```
53

54
### setuptools Integration
55

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

58
```python { .api }
59
def rust_extensions(
60
    dist: Distribution, 
61
    attr: Literal["rust_extensions"], 
62
    value: List[RustExtension]
63
) -> None:
64
    """
65
    Setup keyword handler for rust_extensions.
66

67
    Parameters:
68
    - dist: Distribution instance
69
    - attr: Attribute name (always "rust_extensions")
70
    - value: List of RustExtension instances
71
    """
72

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

77
    Parameters:
78
    - dist: Distribution instance to configure
79
    """
80

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

85
    Parameters:
86
    - dist: Distribution instance to enhance
87
    """
88
```
89

90
### Entry Points
91

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

94
#### Distutils Commands
95
```python { .api }
96
# Entry points for distutils commands
97
build_rust = "setuptools_rust:build_rust"
98
clean_rust = "setuptools_rust:clean_rust"
99
```
100

101
#### Setup Keywords
102
```python { .api }
103
# Entry point for setup() keyword arguments
104
rust_extensions = "setuptools_rust.setuptools_ext:rust_extensions"
105
```
106

107
#### Distribution Finalization
108
```python { .api }
109
# Entry point for pyproject.toml integration
110
setuptools_rust = "setuptools_rust.setuptools_ext:pyprojecttoml_config"
111
```
112

113
## Configuration Examples
114

115
### Basic Extension Setup
116

117
```toml
118
[build-system]
119
requires = ["setuptools", "setuptools-rust"]
120
build-backend = "setuptools.build_meta"
121

122
[project]
123
name = "my-rust-extension"
124
version = "0.1.0"
125

126
[[tool.setuptools-rust.ext-modules]]
127
target = "my_package.rust_module"
128
path = "rust/Cargo.toml"
129
binding = "PyO3"
130
```
131

132
### Multiple Extensions with Different Bindings
133

134
```toml
135
[[tool.setuptools-rust.ext-modules]]
136
target = "my_package.pyo3_module"
137
path = "pyo3/Cargo.toml"
138
binding = "PyO3"
139
features = ["python-extension"]
140

141
[[tool.setuptools-rust.ext-modules]]
142
target = "my_package.cpython_module"  
143
path = "cpython/Cargo.toml"
144
binding = "RustCPython"
145
debug = true
146
```
147

148
### Cross-compilation Configuration
149

150
```toml
151
[[tool.setuptools-rust.ext-modules]]
152
target = "my_package.cross_module"
153
path = "Cargo.toml"
154
args = ["--target", "aarch64-apple-darwin"]
155

156
[tool.setuptools-rust.ext-modules.env]
157
CARGO_BUILD_TARGET = "aarch64-apple-darwin"
158
```
159

160
### Release Optimization
161

162
```toml
163
[[tool.setuptools-rust.ext-modules]]
164
target = "my_package.optimized"
165
path = "Cargo.toml"
166
debug = false
167
strip = "All"
168
rustc-flags = ["-C", "target-cpu=native", "-C", "opt-level=3"]
169
features = ["simd", "optimizations"]
170
```
171

172
### Development Configuration
173

174
```toml
175
[[tool.setuptools-rust.ext-modules]]
176
target = "my_package.dev_module"
177
path = "Cargo.toml"
178
debug = true
179
quiet = false
180
rustc-flags = ["-C", "debuginfo=2"]
181
features = ["debugging", "profiling"]
182
```
183

184
### Binary Tools
185

186
```toml
187
[[tool.setuptools-rust.bins]]
188
target = "my-cli-tool"
189
path = "cli/Cargo.toml"
190
strip = "Debug"
191
features = ["cli"]
192

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

199
### Environment Variable Configuration
200

201
```toml
202
[[tool.setuptools-rust.ext-modules]]
203
target = "my_package.configured"
204
path = "Cargo.toml"
205

206
[tool.setuptools-rust.ext-modules.env]
207
RUSTFLAGS = "-C target-feature=+crt-static"
208
CARGO_PROFILE_RELEASE_LTO = "true"
209
CUSTOM_BUILD_VAR = "production"
210
```
211

212
### Optional Extensions
213

214
```toml
215
[[tool.setuptools-rust.ext-modules]]
216
target = "my_package.optional_feature"
217
path = "optional/Cargo.toml"
218
optional = true
219
quiet = true
220
features = ["experimental"]
221
```
222

223
## Legacy setup.py Integration
224

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

227
```python
228
from setuptools import setup
229
from setuptools_rust import RustExtension, Binding
230

231
setup(
232
    name="my-package",
233
    version="0.1.0",
234
    rust_extensions=[
235
        RustExtension(
236
            "my_package.rust_module",
237
            path="Cargo.toml",
238
            binding=Binding.PyO3,
239
            features=["python-extension"],
240
            debug=False,
241
        )
242
    ],
243
    zip_safe=False,  # Rust extensions are not zip safe
244
)
245
```
246

247
## Configuration Validation
248

249
setuptools-rust validates configuration at build time:
250

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

257
## Build Profile Override
258

259
The cargo build profile can be overridden using environment variables:
260

261
```bash
262
# Override profile for all extensions
263
export SETUPTOOLS_RUST_CARGO_PROFILE=release
264

265
# Build with custom profile
266
python setup.py build_rust
267
```
268

269
Or through configuration:
270

271
```toml
272
[[tool.setuptools-rust.ext-modules]]
273
target = "my_package.module"
274
args = ["--profile", "custom-profile"]
275
```
276

277
## Type Definitions
278

279
```python { .api }
280
from typing import List, Dict, Literal, Optional
281
from setuptools import Distribution
282

283
# Configuration types
284
ConfigSection = Dict[str, Any]
285
ExtModuleConfig = Dict[str, Any]
286
BinConfig = Dict[str, Any]
287
```