Debian Codegraph @

subprojects/meson-docs/docs/markdown/Rust-module.md

raw
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