README.md 3.23 KB
Newer Older
Ryan Hunt's avatar
Ryan Hunt committed
1
2
3
4
5
6
# `cbindgen`   [![Build Status]][travis] [![Latest Version]][crates.io]

[Build Status]: https://api.travis-ci.org/rlhunt/cbindgen.svg?branch=master
[travis]: https://travis-ci.org/rlhunt/cbindgen
[Latest Version]: https://img.shields.io/crates/v/cbindgen.svg
[crates.io]: https://crates.io/crates/cbindgen
Kartikaya Gupta's avatar
Kartikaya Gupta committed
7

Ryan Hunt's avatar
Ryan Hunt committed
8
This project can be used to generate C bindings for Rust code. It is currently being developed to support creating bindings for [WebRender](https://github.com/servo/webrender/), but has been designed to support any project.
Kartikaya Gupta's avatar
Kartikaya Gupta committed
9

10
11
12
13
## Features

  * Builds bindings for a crate, its mods, its dependent crates, and their mods
  * Only the necessary types for exposed functions are given bindings
Ryan Hunt's avatar
Ryan Hunt committed
14
  * Can specify annotations for controlling some aspects of binding
15
  * Generic structs can be exposed using `type IntFoo = Foo<i32>;`
Ryan Hunt's avatar
Ryan Hunt committed
16
  * Customizable formatting, can be used in C or C++ projects
17

Ryan Hunt's avatar
Ryan Hunt committed
18
## Use
Kartikaya Gupta's avatar
Kartikaya Gupta committed
19

20
21
### Command line

Ryan Hunt's avatar
Ryan Hunt committed
22
`cbindgen crate/ -o crate/bindings.h`
Ryan Hunt's avatar
Ryan Hunt committed
23

24
25
26
27
28
29
30
31
32
33
See `cbindgen --help` for more options.

### `build.rs`

`cbindgen` can also be used in build scripts. How this fits into compiling the native code depends on your project.

Here's an example build.rs script:
```rust
extern crate cbindgen;

34
use std::env;
35
36

fn main() {
Ryan Hunt's avatar
Ryan Hunt committed
37
38
39
40
41
    let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();

    cbindgen::generate(crate_dir)
      .unwrap()
      .write_to_file("bindings.h");
42
}
Ryan Hunt's avatar
Ryan Hunt committed
43

44
45
```

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
## Configuration

There are a lot of configurable options for binding generation. Options can be specified by creating a `cbindgen.toml` with the options in the binding crate root. Alternatively, build scripts can specify options using `cbindgen::generate_with_config`.

Some useful options:

1. `header` - Optional text to output at the beginning of the file
2. `trailer` - Optional text to output at the end of the file
3. `include_guard` - Optional name to use for an include guard
4. `autogen_warning` - Optional text to output at major sections to deter manual editing
5. `include_version` - Whether to include a comment with the version of cbindgen used to generate the file
6. `braces` - The style to use for braces (can be either SameLine or NextLine)
7. `line_length` - The preferred length of a line, used when auto breaking function arguments
8. `tab_width` - The amount of spaces in an indentation
9. `language` - The language to generate bindings in (can be either C++ or C)
10. `parse_deps` - Whether to parse dependent crates
11. `include` - An optional whitelist to use when parsing dependent crates
12. `exclude` - An optional blacklist to use when parsing dependent crates

A full listing of options can be found in `src/bindgen/config.rs`

67
68
## Examples

Ryan Hunt's avatar
Ryan Hunt committed
69
See `compile-tests/` for some examples of rust source that can be handled.
70

Ryan Hunt's avatar
Ryan Hunt committed
71
72
73
74
## How it works

1. All the structs, enums, type aliases, and functions that are representable in C are gathered
2. A dependency graph is built using the extern "C" functions as roots
75
    * This removes unneeded types from the bindings and sorts the structs that depend on each other
Ryan Hunt's avatar
Ryan Hunt committed
76
77
78
79
80
3. Some code generation is done to specialize generics that are specified as type aliases
3. The items are printed in dependency order in C syntax

## Future work

81
82
83
1. Better support for types with fully specified names
2. Support for generating a FFI interface for a Struct+Impl
3. ...