Debian Codegraph @

.cargo/vendor/cbindgen/README.md

raw
1 # `cbindgen`   [![Build Status]][actions] [![Latest Version]][crates.io] [![Api Rustdoc]][rustdoc] [![Rust](https://img.shields.io/badge/rust-1.57%2B-blue.svg?maxAge=3600)](https://github.com/eqrion/cbindgen)
2
3 [Build Status]: https://github.com/eqrion/cbindgen/workflows/cbindgen/badge.svg
4 [actions]: https://github.com/eqrion/cbindgen/actions
5 [Latest Version]: https://img.shields.io/crates/v/cbindgen.svg
6 [crates.io]: https://crates.io/crates/cbindgen
7 [Api Rustdoc]: https://img.shields.io/badge/api-rustdoc-blue.svg
8 [rustdoc]: https://docs.rs/cbindgen
9
10 [Read the full user docs here!](docs.md)
11
12 cbindgen creates C/C++11 headers for Rust libraries which expose a public C API.
13
14 While you could do this by hand, it's not a particularly good use of your time.
15 It's also much more likely to be error-prone than machine-generated headers that
16 are based on your actual Rust code. The cbindgen developers have also worked
17 closely with the developers of Rust to ensure that the headers we generate
18 reflect actual guarantees about Rust's type layout and ABI.
19
20 C++ headers are nice because we can use operator overloads, constructors, enum
21 classes, and templates to make the API more ergonomic and Rust-like. C headers
22 are nice because you can be more confident that whoever you're interoperating
23 with can handle them. With cbindgen *you don't need to choose*! You can just
24 tell it to emit both from the same Rust library.
25
26 There are two ways to use cbindgen: as a standalone program, or as a library
27 (presumably in your build.rs). There isn't really much practical difference,
28 because cbindgen is a simple rust library with no interesting dependencies.
29
30 Using it as a program means people building your software will need it
31 installed. Using it in your library means people may have to build cbindgen more
32 frequently (e.g. every time they update their rust compiler).
33
34 It's worth noting that the development of cbindgen has been largely adhoc, as
35 features have been added to support the usecases of the maintainers. This means
36 cbindgen may randomly fail to support some particular situation simply because
37 no one has put in the effort to handle it yet. [Please file an issue if you run
38 into such a situation](https://github.com/eqrion/cbindgen/issues/new). Although
39 since we all have other jobs, you might need to do the implementation work too
40 :)
41
42 # Quick Start
43
44 To install cbindgen, you just need to run
45
46 ```text
47 cargo install --force cbindgen
48 ```
49
50 (--force just makes it update to the latest cbindgen if it's already installed)
51
52 Or with Homebrew, run
53
54 ```text
55 brew install cbindgen
56 ```
57
58 To use cbindgen you need two things:
59
60 * A configuration (cbindgen.toml, which can be empty to start)
61 * A Rust crate with a public C API
62
63 Then all you need to do is run it:
64
65 ```text
66 cbindgen --config cbindgen.toml --crate my_rust_library --output my_header.h
67 ```
68
69 This produces a header file for C++. For C, add the `--lang c` switch.
70
71 See `cbindgen --help` for more options.
72
73 [Read the full user docs here!](docs.md)
74
75 [Get a template cbindgen.toml here.](template.toml)
76
77 # Examples
78
79 We don't currently have a nice tailored example application, but [the
80 tests](tests/rust/) contain plenty of interesting examples of our features.
81
82 You may also find it interesting to browse the projects that are using cbindgen
83 in production:
84
85 * [milksnake](https://github.com/getsentry/milksnake)
86 * [webrender](https://searchfox.org/mozilla-central/source/gfx/webrender_bindings) ([generated header](https://searchfox.org/mozilla-central/source/__GENERATED__/gfx/webrender_bindings/webrender_ffi_generated.h))
87 * [stylo](https://searchfox.org/mozilla-central/source/layout/style) ([generated header](https://searchfox.org/mozilla-central/source/__GENERATED__/layout/style/ServoStyleConsts.h))
88 * [maturin](https://github.com/PyO3/maturin)
89
90 If you're using `cbindgen` and would like to be added to this list, please open
91 a pull request!
92
93 # Releases
94
95 cbindgen doesn't have a fixed release calendar, please file an issue requesting
96 a release if there's something fixed in trunk that you need released. Ping
97 `@emilio` for increased effect.