Debian Codegraph @

guide/src/config.md

raw
1 # Configuration
2
3 ## Configuration format
4
5 You can configure maturin in `tool.maturin` section of [`pyproject.toml`](https://peps.python.org/pep-0518/#tool-table).
6
7 ## Configuration keys
8
9 ### Cargo options
10
11 ```toml
12 [tool.maturin]
13 # Build artifacts with the specified Cargo profile
14 profile = "release"
15 # List of features to activate
16 features = ["foo", "bar"]
17 # Activate all available features
18 all-features = false
19 # Do not activate the `default` feature
20 no-default-features = false
21 # Cargo manifest path
22 manifest-path = "Cargo.toml"
23 # Require Cargo.lock and cache are up to date
24 frozen = false
25 # Require Cargo.lock is up to date
26 locked = false
27 # Override a configuration value (unstable)
28 config = []
29 # Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
30 unstable-flags = []
31 # Extra arguments that will be passed to rustc as `cargo rustc [...] -- [...] [arg1] [arg2]`
32 rustc-args = []
33 ```
34
35 These are `cargo` build options, refer Cargo documentation [here](https://doc.rust-lang.org/cargo/commands/cargo-rustc.html).
36
37 ### maturin options
38
39 ```toml
40 [tool.maturin]
41 # Include additional files
42 include = []
43 # Exclude files
44 exclude = []
45 # Bindings type
46 bindings = "pyo3"
47 # Control the platform tag and PyPI compatibility
48 compatibility = "pypi"
49 # auditwheel mode, possible values are repair, check and skip
50 auditwheel = "repair"
51 # Don't check for manylinux compliance, deprecated in favor of auditwheel = "audit"
52 skip-auditwheel = false
53 # Python source directory
54 python-source = "src"
55 # Python packages to include
56 python-packages = ["foo", "bar"]
57 # Strip the library for minimum file size
58 strip = true
59 # Source distribution generator,
60 # supports cargo (default) and git.
61 sdist-generator = "cargo"
62 # Use base Python executable instead of venv Python executable in PEP 517 build.
63 #
64 # This can help avoid unnecessary rebuilds, as the Python executable does not change
65 # every time. It should not be set when the sdist build requires packages installed
66 # in venv. This can also be set with the `MATURIN_PEP517_USE_BASE_PYTHON` environment
67 # variable.
68 use-base-python = false
69 ```
70
71 The `[tool.maturin.include]` and `[tool.maturin.exclude]` configuration are
72 inspired by
73 [Poetry](https://python-poetry.org/docs/pyproject/#include-and-exclude).
74
75 To specify files or globs directly:
76
77 ```toml
78 include = ["path/**/*", "some/other/file"]
79 ```
80
81 To specify a specific target format (`sdist` or `wheel`):
82
83 ```toml
84 include = [
85 { path = "path/**/*", format = "sdist" },
86 { path = "all", format = ["sdist", "wheel"] },
87 { path = "for/wheel/**/*", format = "wheel" }
88 ]
89 ```
90
91 The default behavior is apply these configurations to both `sdist` and `wheel`
92 targets.
93
94 #### target specific maturin options
95
96 Currently only macOS deployment target SDK version can be configured
97 for `x86_64-apple-darwin` and `aarch64-apple-darwin` targets, other targets
98 have no options yet.
99
100 ```toml
101 [tool.maturin.target.<triple>]
102 # macOS deployment target SDK version
103 macos-deployment-target = "11.0"
104 ```