1--- 2short-description: Rust language integration module 3authors: 4 - name: Dylan Baker 5 email: dylan@pnwbakers.com 6 years: [2020, 2021] 7... 8 9# Unstable Rust module 10 11*(new in 0.57.0)* 12 13**Note** Unstable modules make no backwards compatible API guarantees. 14 15The rust module provides helper to integrate rust code into Meson. The 16goal is to make using rust in Meson more pleasant, while still 17remaining mesonic, this means that it attempts to make Rust work more 18like Meson, rather than Meson work more like rust. 19 20## Functions 21 22### test(name: string, target: library | executable, dependencies: []Dependency) 23 24This function creates a new rust unittest target from an existing rust 25based target, which may be a library or executable. It does this by 26copying the sources and arguments passed to the original target and 27adding the `--test` argument to the compilation, then creates a new 28test target which calls that executable, using the rust test protocol. 29 30This accepts all of the keyword arguments as the 31[`test`](Reference-manual.md#test) function except `protocol`, it will set 32that automatically. 33 34Additional, test only dependencies may be passed via the dependencies 35argument. 36 37### bindgen(*, input: string | BuildTarget | []string | []BuildTarget, output: strng, include_directories: []include_directories, c_args: []string, args: []string) 38 39This function wraps bindgen to simplify creating rust bindings around C 40libraries. This has two advantages over hand-rolling ones own with a 41`generator` or `custom_target`: 42 43- It handles `include_directories`, so one doesn't have to manually convert them to `-I...` 44- It automatically sets up a depfile, making the results more reliable 45 46 47It takes the following keyword arguments 48 49- input — A list of Files, Strings, or CustomTargets. The first element is 50 the header bindgen will parse, additional elements are dependencies. 51- output — the name of the output rust file 52- include_directories — A list of `include_directories` objects, these are 53 passed to clang as `-I` arguments 54- c_args — A list of string arguments to pass to clang untouched 55- args — A list of string arguments to pass to `bindgen` untouched. 56 57```meson 58rust = import('unstable-rust') 59 60inc = include_directories('..'¸ '../../foo') 61 62generated = rust.bindgen( 63 'myheader.h', 64 'generated.rs', 65 include_directories : [inc, include_directories('foo')], 66 args : ['--no-rustfmt-bindings'], 67 c_args : ['-DFOO=1'], 68) 69``` 70 71If the header depeneds on generated headers, those headers must be passed to 72`bindgen` as well to ensure proper dependency ordering, static headers do not 73need to be passed, as a proper depfile is generated: 74 75```meson 76h1 = custom_target(...) 77h2 = custom_target(...) 78 79r1 = rust.bindgen( 80 [h1, h2], # h1 includes h2, 81 'out.rs', 82) 83``` 84