| 1 |
--- |
| 2 |
short-description: Rust language integration module |
| 3 |
authors: |
| 4 |
- name: Dylan Baker |
| 5 |
email: [email protected] |
| 6 |
years: [2020, 2021, 2022, 2024] |
| 7 |
... |
| 8 |
|
| 9 |
# Rust module |
| 10 |
|
| 11 |
*(new in 0.57.0)* |
| 12 |
*(Stable since 1.0.0)* |
| 13 |
|
| 14 |
The rust module provides helper to integrate rust code into Meson. The |
| 15 |
goal is to make using rust in Meson more pleasant, while still |
| 16 |
remaining mesonic, this means that it attempts to make Rust work more |
| 17 |
like Meson, rather than Meson work more like rust. |
| 18 |
|
| 19 |
## Functions |
| 20 |
|
| 21 |
### test() |
| 22 |
|
| 23 |
```meson |
| 24 |
rustmod.test(name, target, ...) |
| 25 |
``` |
| 26 |
|
| 27 |
This function creates a new rust unittest target from an existing rust |
| 28 |
based target, which may be a library or executable. It does this by |
| 29 |
copying the sources and arguments passed to the original target and |
| 30 |
adding the `--test` argument to the compilation, then creates a new |
| 31 |
test target which calls that executable, using the rust test protocol. |
| 32 |
|
| 33 |
This function takes two positional arguments, the first is the name of the |
| 34 |
test and the second is the library or executable that is the rust based target. |
| 35 |
It also takes the following keyword arguments: |
| 36 |
|
| 37 |
- `dependencies`: a list of test-only Dependencies |
| 38 |
- `link_with`: a list of additional build Targets to link with (*since 1.2.0*) |
| 39 |
- `rust_args`: a list of extra arguments passed to the Rust compiler (*since 1.2.0*) |
| 40 |
|
| 41 |
This function also accepts all of the keyword arguments accepted by the |
| 42 |
[[test]] function except `protocol`, it will set that automatically. |
| 43 |
|
| 44 |
### bindgen() |
| 45 |
|
| 46 |
This function wraps bindgen to simplify creating rust bindings around C |
| 47 |
libraries. This has two advantages over invoking bindgen with a |
| 48 |
`generator` or `custom_target`: |
| 49 |
|
| 50 |
- It handles `include_directories`, so one doesn't have to manually convert them to `-I...` |
| 51 |
- It automatically sets up a depfile, making the results more reliable |
| 52 |
- It automatically handles assertions, synchronizing Rust and C/C++ to have the same behavior |
| 53 |
|
| 54 |
|
| 55 |
It takes the following keyword arguments |
| 56 |
|
| 57 |
- `input`: a list of Files, Strings, or CustomTargets. The first element is |
| 58 |
the header bindgen will parse, additional elements are dependencies. |
| 59 |
- `output`: the name of the output rust file |
| 60 |
- `output_inline_wrapper`: the name of the optional output c file containing |
| 61 |
wrappers for static inline function. This requires `bindgen-0.65` or |
| 62 |
newer (*since 1.3.0*). |
| 63 |
- `include_directories`: A list of `include_directories` or `string` objects, |
| 64 |
these are passed to clang as `-I` arguments *(string since 1.0.0)* |
| 65 |
- `c_args`: a list of string arguments to pass to clang untouched |
| 66 |
- `args`: a list of string arguments to pass to `bindgen` untouched. |
| 67 |
- `dependencies`: a list of `Dependency` objects to pass to the underlying clang call (*since 1.0.0*) |
| 68 |
- `language`: A literal string value of `c` or `cpp`. When set this will force bindgen to treat a source as the given language. Defaults to checking based on the input file extension. *(since 1.4.0)* |
| 69 |
- `bindgen_version`: a list of string version values. When set the found bindgen binary must conform to these constraints. *(since 1.4.0)* |
| 70 |
|
| 71 |
```meson |
| 72 |
rust = import('unstable-rust') |
| 73 |
|
| 74 |
inc = include_directories('..'ΒΈ '../../foo') |
| 75 |
|
| 76 |
generated = rust.bindgen( |
| 77 |
input : 'myheader.h', |
| 78 |
output : 'generated.rs', |
| 79 |
include_directories : [inc, include_directories('foo')], |
| 80 |
args : ['--no-rustfmt-bindings'], |
| 81 |
c_args : ['-DFOO=1'], |
| 82 |
) |
| 83 |
``` |
| 84 |
|
| 85 |
If the header depends on generated headers, those headers must be passed to |
| 86 |
`bindgen` as well to ensure proper dependency ordering, static headers do not |
| 87 |
need to be passed, as a proper depfile is generated: |
| 88 |
|
| 89 |
```meson |
| 90 |
h1 = custom_target(...) |
| 91 |
h2 = custom_target(...) |
| 92 |
|
| 93 |
r1 = rust.bindgen( |
| 94 |
input : [h1, h2], # h1 includes h2, |
| 95 |
output : 'out.rs', |
| 96 |
) |
| 97 |
``` |
| 98 |
|
| 99 |
*Since 1.1.0* Meson will synchronize assertions for Rust and C/C++ when the |
| 100 |
`b_ndebug` option is set (via `-DNDEBUG` for C/C++, and `-C |
| 101 |
debug-assertions=on` for Rust), and will pass `-DNDEBUG` as an extra argument |
| 102 |
to clang. This allows for reliable wrapping of `-DNDEBUG` controlled behavior |
| 103 |
with `#[cfg(debug_asserions)]` and or `cfg!()`. Before 1.1.0, assertions for Rust |
| 104 |
were never turned on by Meson. |
| 105 |
|
| 106 |
*Since 1.2.0* Additional arguments to pass to clang may be specified in a |
| 107 |
*machine file in the properties section: |
| 108 |
|
| 109 |
```ini |
| 110 |
[properties] |
| 111 |
bindgen_clang_arguments = ['-target', 'x86_64-linux-gnu'] |
| 112 |
``` |
| 113 |
|
| 114 |
### proc_macro() |
| 115 |
|
| 116 |
```meson |
| 117 |
rustmod.proc_macro(name, sources, ...) |
| 118 |
``` |
| 119 |
|
| 120 |
*Since 1.3.0* |
| 121 |
|
| 122 |
This function creates a Rust `proc-macro` crate, similar to: |
| 123 |
```meson |
| 124 |
[[shared_library]](name, sources, |
| 125 |
rust_crate_type: 'proc-macro', |
| 126 |
native: true) |
| 127 |
``` |
| 128 |
|
| 129 |
`proc-macro` targets can be passed to `link_with` keyword argument of other Rust |
| 130 |
targets. |
| 131 |
|
| 132 |
Only a subset of [[shared_library]] keyword arguments are allowed: |
| 133 |
- rust_args |
| 134 |
- rust_dependency_map |
| 135 |
- sources |
| 136 |
- dependencies |
| 137 |
- extra_files |
| 138 |
- link_args |
| 139 |
- link_depends |
| 140 |
- link_with |
| 141 |
- override_options |