Debian Codegraph @

guide/src/bindings.md

raw
1 # Bindings
2
3 Maturin supports several kinds of bindings, some of which are automatically
4 detected. You can also pass `-b` / `--bindings` command line option to manually
5 specify which bindings to use.
6
7 ## `pyo3`
8
9 [pyo3](https://github.com/PyO3/pyo3) is Rust bindings for Python,
10 including tools for creating native Python extension modules.
11 It supports CPython, PyPy, and GraalPy.
12
13 maturin automatically detects pyo3 bindings when it's added as a dependency in `Cargo.toml`.
14
15 ### `Py_LIMITED_API`/abi3
16
17 pyo3 bindings has `Py_LIMITED_API`/abi3 support, enable the `abi3` feature of the `pyo3` crate to use it:
18
19 ```toml
20 pyo3 = { version = "0.25", features = ["abi3"] }
21 ```
22
23 You may additionally specify a minimum Python version by using the `abi3-pyXX`
24 format for the pyo3 features, where `XX` is corresponds to a Python version.
25 For example `abi3-py37` will indicate a minimum Python version of 3.7.
26
27 > **Note**: Read more about abi3 support in [pyo3's
28 > documentation](https://pyo3.rs/latest/building-and-distribution#py_limited_apiabi3).
29
30 ### Cross Compiling
31
32 pyo3 bindings has decent cross compilation support.
33 For manylinux support the [manylinux-cross](https://github.com/rust-cross/manylinux-cross) docker images can be used.
34
35 > **Note**: Read more about cross compiling in [pyo3's
36 > documentation](https://pyo3.rs/latest/building-and-distribution#cross-compiling).
37
38 ## `cffi`
39
40 Cffi wheels are compatible with all python versions including pypy. If `cffi`
41 isn't installed and python is running inside a virtualenv, maturin will install
42 it, otherwise you have to install it yourself (`pip install cffi`).
43
44 Maturin uses cbindgen to generate a header file for [supported Rust
45 types](https://github.com/eqrion/cbindgen/blob/master/docs.md#supported-types).
46 The header file can be customized by configuring cbindgen through a
47 `cbindgen.toml` file inside your project root. Aternatively you can use a build
48 script that writes a header file to `$PROJECT_ROOT/target/header.h`, like so:
49
50 ```rust
51 use cbindgen;
52 use std::env;
53 use std::path::Path;
54
55 fn main() {
56 let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
57
58 let bindings = cbindgen::Builder::new()
59 .with_no_includes()
60 .with_language(cbindgen::Language::C)
61 .with_crate(crate_dir)
62 .generate()
63 .unwrap();
64 bindings.write_to_file(Path::new("target").join("header.h"));
65 }
66 ```
67
68 Maturin uses the cbindgen-generated header to create a module that exposes `ffi` and
69 `lib` objects as attributes. See the [cffi docs](https://cffi.readthedocs.io/en/latest/using.html)
70 for more information on using these `ffi`/`lib` objects to call the Rust code
71 from Python.
72
73 > **Note**: Maturin _does not_ automatically detect `cffi` bindings. You _must_
74 > specify them via either command line with `-b cffi` or in `pyproject.toml`.
75
76 Maturin automatically detect `cffi` bindings, but only if there is no pyo3
77 dependency. You can specify `cffi` explicitly via either command line with
78 `-b cffi` or in `pyproject.toml`.
79
80 ## `bin`
81
82 Maturin also supports distributing binary applications written in Rust as
83 Python packages using the `bin` bindings. Binaries are packaged into the wheel
84 as "scripts" and are available on the user's `PATH` (e.g. in the `bin`
85 directory of a virtual environment) once installed.
86
87 Maturin automatically detect `bin` bindings, but only if there
88 is only a binary target and no pyo3 dependency or cdylib target. You can
89 specify `bin` explicitly via either command line with `-b bin` or in `pyproject.toml`.
90
91 ### Both binary and library?
92
93 Shipping both a binary and library would double the size of your wheel. Consider instead exposing a CLI function in the library and using a Python entrypoint:
94
95 ```rust
96 #[pyfunction]
97 fn print_cli_args(py: Python) -> PyResult<()> {
98 // This one includes python and the name of the wrapper script itself, e.g.
99 // `["/home/ferris/.venv/bin/python", "/home/ferris/.venv/bin/print_cli_args", "a", "b", "c"]`
100 println!("{:?}", env::args().collect::<Vec<_>>());
101 // This one includes only the name of the wrapper script itself, e.g.
102 // `["/home/ferris/.venv/bin/print_cli_args", "a", "b", "c"])`
103 println!(
104 "{:?}",
105 py.import("sys")?
106 .getattr("argv")?
107 .extract::<Vec<String>>()?
108 );
109 Ok(())
110 }
111
112 #[pymodule]
113 fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
114 m.add_wrapped(wrap_pyfunction!(print_cli_args))?;
115
116 Ok(())
117 }
118 ```
119
120 In pyproject.toml:
121
122 ```toml
123 [project.scripts]
124 print_cli_args = "my_module:print_cli_args"
125 ```
126
127 ## `uniffi`
128
129 uniffi bindings use [uniffi-rs](https://mozilla.github.io/uniffi-rs/) to generate Python `ctypes` bindings
130 from an interface definition file. uniffi wheels are compatible with all python versions including pypy.