| 1 |
# `cbindgen`   [![Build Status]][actions] [![Latest Version]][crates.io] [![Api Rustdoc]][rustdoc] [](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. |