diff options
author | Dylan Baker <dylan@pnwbakers.com> | 2021-01-06 11:28:50 -0800 |
---|---|---|
committer | Dylan Baker <dylan@pnwbakers.com> | 2021-02-06 10:27:04 -0800 |
commit | b28235428df69ba0a90a8f7c0f26db8527ec68a7 (patch) | |
tree | 10df8a0b264bf493cbf7de3807e5a56a97d959ab /docs | |
parent | 9d441d26d20a8bd79edd2180160238771fe8c28d (diff) | |
download | meson-b28235428df69ba0a90a8f7c0f26db8527ec68a7.zip meson-b28235428df69ba0a90a8f7c0f26db8527ec68a7.tar.gz meson-b28235428df69ba0a90a8f7c0f26db8527ec68a7.tar.bz2 |
rust: Add a module wrapper for bindgen
This has a couple of advantages over rolling it by hand:
1. it correctly handles include_directories objects, which is always
handy
2. it correctly generates a depfile for you, which makes it more
reliable
3. it requires less typing
Diffstat (limited to 'docs')
-rw-r--r-- | docs/markdown/Rust-module.md | 50 | ||||
-rw-r--r-- | docs/markdown/snippets/unstable-rust-module.md | 3 |
2 files changed, 51 insertions, 2 deletions
diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md index 9f217ea..fdff483 100644 --- a/docs/markdown/Rust-module.md +++ b/docs/markdown/Rust-module.md @@ -3,7 +3,7 @@ short-description: Rust language integration module authors: - name: Dylan Baker email: dylan@pnwbakers.com - years: [2020] + years: [2020, 2021] ... # Unstable Rust module @@ -33,3 +33,51 @@ that automatically. Additional, test only dependencies may be passed via the dependencies argument. + +### bindgen(*, input: string | BuildTarget | []string | []BuildTarget, output: strng, include_directories: []include_directories, c_args: []string, args: []string) + +This function wraps bindgen to simplify creating rust bindings around C +libraries. This has two advantages over hand-rolling ones own with a +`generator` or `custom_target`: + +- It handles `include_directories`, so one doesn't have to manually convert them to `-I...` +- It automatically sets up a depfile, making the results more reliable + + +It takes the following keyword arguments + +- input — A list of Files, Strings, or CustomTargets. The first element is + the header bindgen will parse, additional elements are dependencies. +- output — the name of the output rust file +- include_directories — A list of `include_directories` objects, these are + passed to clang as `-I` arguments +- c_args — A list of string arguments to pass to clang untouched +- args — A list of string arguments to pass to `bindgen` untouched. + +```meson +rust = import('unstable-rust') + +inc = include_directories('..'¸ '../../foo') + +generated = rust.bindgen( + 'myheader.h', + 'generated.rs', + include_directories : [inc, include_directories('foo'), + args : ['--no-rustfmt-bindings'], + c_args : ['-DFOO=1'], +) +``` + +If the header depeneds on generated headers, those headers must be passed to +`bindgen` as well to ensure proper dependency ordering, static headers do not +need to be passed, as a proper depfile is generated: + +```meson +h1 = custom_target(...) +h2 = custom_target(...) + +r1 = rust.bindgen( + [h1, h2], # h1 includes h2, + 'out.rs', +) +``` diff --git a/docs/markdown/snippets/unstable-rust-module.md b/docs/markdown/snippets/unstable-rust-module.md index e594ecf..87ffe33 100644 --- a/docs/markdown/snippets/unstable-rust-module.md +++ b/docs/markdown/snippets/unstable-rust-module.md @@ -1,4 +1,5 @@ ## Unstable Rust module A new unstable module has been added to make using Rust with Meson easier. -Currently it adds a single function to ease defining Rust tests. +Currently, it adds a single function to ease defining Rust tests, as well as a +wrapper around bindgen, making it easier to use. |