README.md 5.07 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
## Configuration

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
There are some options that can be used to configure the binding generation. They can be specified by creating a `cbindgen.toml` with the options in the binding crate root or at a path manually specified through the command line. Alternatively, build scripts can specify them using `cbindgen::generate_with_config`.

Here is a description of the options available in a config.

```toml
# An optional string of text to output at the beginning of the generated file
header = <string>
# An optional string of text to output at the end of the generated file
trailer = <string>
# An optional name to use as an include guard
include_guard = <string>
# An optional string of text to output between major sections of the generated
# file as a warning against manual editing
autogen_warning = <string>
# Whether to include a comment with the version of cbindgen used to generate the
# file
include_version = <bool>
# An optional namespace to output around the generated bindings
namespace = <string>
# An optional list of namespaces to output around the generated bindings
namespaces = [<string>]
# The style to use for curly braces
braces = <curly>
# The desired length of a line to use when formatting lines
line_length = <integer>
# The amount of spaces in a tab
tab_width = <integer>
# The language to output bindings in
language = <language>

[parse]
# Whether to parse dependent crates and include their types in the generated
# bindings
parse_deps = <bool>
# A white list of crate names that are allowed to be parsed
include = [<string>]
# A black list of crate names that are not allowed to be parsed
exclude = [<string>]
# A list of crate names that should be run through `cargo expand` before
# parsing to expand any macros
expand = [<string>]

[fn]
# An optional prefix to put before every function declaration
prefix = <string>
# An optional postfix to put after any function declaration
postfix = <string>
# How to format function arguments
args = <layout>
# A rule to use to rename function argument names
rename_args = <rename-rule>

[struct]
# A rule to use to rename field names
rename_fields = <rename-rule>
# Whether to derive an operator== for all structs
derive_eq = <bool>
# Whether to derive an operator!= for all structs
derive_neq = <bool>
# Whether to derive an operator< for all structs
derive_lt = <bool>
# Whether to derive an operator<= for all structs
derive_lte = <bool>
# Whether to derive an operator> for all structs
derive_gt = <bool>
# Whether to derive an operator>= for all structs
derive_gte = <bool>

[enum]
# A rule to use to rename enum variants
rename_variants = <rename-rule>

# With

<curly> = ["SameLine" | "NextLine"]
<language> = ["C++" | "C"]
<layout> = ["Auto" |
            "Vertical" |
            "Horizontal"]
<rename-rule> = ["None" |
                 "GeckoCase" |
                 "LowerCase" |
                 "UpperCase" |
                 "PascalCase" |
                 "CamelCase" |
                 "SnakeCase" |
                 "ScreamingSnakeCase" |
                 "QualifiedScreamingSnakeCase"]
```
137

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

140
141
## Examples

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

Ryan Hunt's avatar
Ryan Hunt committed
144
145
146
147
## 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
148
    * This removes unneeded types from the bindings and sorts the structs that depend on each other
Ryan Hunt's avatar
Ryan Hunt committed
149
3. Some code generation is done to specialize generics that are specified as type aliases
150
4. The items are printed in dependency order in C syntax
Ryan Hunt's avatar
Ryan Hunt committed
151
152
153

## Future work

154
155
156
1. Better support for types with fully specified names
2. Support for generating a FFI interface for a Struct+Impl
3. ...