README.md 6.01 KB
Newer Older
Ryan Hunt's avatar
Ryan Hunt committed
1
# `cbindgen`   [![Build Status]][travis] [![Latest Version]][crates.io] [![Api Rustdoc]][rustdoc]
Ryan Hunt's avatar
Ryan Hunt committed
2

Ryan Hunt's avatar
Ryan Hunt committed
3
[Build Status]: https://api.travis-ci.org/eqrion/cbindgen.svg?branch=master
Ryan Hunt's avatar
Ryan Hunt committed
4
[travis]: https://travis-ci.org/eqrion/cbindgen
Ryan Hunt's avatar
Ryan Hunt committed
5
6
[Latest Version]: https://img.shields.io/crates/v/cbindgen.svg
[crates.io]: https://crates.io/crates/cbindgen
Ryan Hunt's avatar
Ryan Hunt committed
7
8
[Api Rustdoc]: https://img.shields.io/badge/api-rustdoc-blue.svg
[rustdoc]: https://eqrion.github.io/cbindgen/cbindgen
Kartikaya Gupta's avatar
Kartikaya Gupta committed
9

Ryan Hunt's avatar
Ryan Hunt committed
10
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
11

12
13
14
15
## 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
16
  * Can specify annotations for controlling some aspects of binding
Ryan Hunt's avatar
Ryan Hunt committed
17
18
  * Support for generic structs and unions
  * Support for exporting constants and statics
Ryan Hunt's avatar
Ryan Hunt committed
19
  * Customizable formatting, can be used in C or C++ projects
Ryan Hunt's avatar
Ryan Hunt committed
20
  * Support for generating `#ifdef`'s for `#[cfg]` attributes
21

Ryan Hunt's avatar
Ryan Hunt committed
22
## Use
Kartikaya Gupta's avatar
Kartikaya Gupta committed
23

24
25
### Command line

Ryan Hunt's avatar
Ryan Hunt committed
26
`cbindgen crate/ -o crate/bindings.h`
Ryan Hunt's avatar
Ryan Hunt committed
27

28
29
30
31
32
33
34
35
36
37
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;

38
use std::env;
39
40

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

RazrFalcon's avatar
RazrFalcon committed
43
    cbindgen::generate(&crate_dir)
Ryan Hunt's avatar
Ryan Hunt committed
44
45
      .unwrap()
      .write_to_file("bindings.h");
46
}
Ryan Hunt's avatar
Ryan Hunt committed
47

48
49
```

50
51
## Configuration

52
53
54
55
56
57
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
Ryan Hunt's avatar
Ryan Hunt committed
58
header = "/* Text to put at the beginning of the generated file. Probably a license. */"
59
# An optional string of text to output at the end of the generated file
Ryan Hunt's avatar
Ryan Hunt committed
60
trailer = "/* Text to put at the end of the generated file */"
61
# An optional name to use as an include guard
Ryan Hunt's avatar
Ryan Hunt committed
62
include_guard = "mozilla_wr_bindings_h"
63
64
# An optional string of text to output between major sections of the generated
# file as a warning against manual editing
Ryan Hunt's avatar
Ryan Hunt committed
65
autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
66
67
# Whether to include a comment with the version of cbindgen used to generate the
# file
Ryan Hunt's avatar
Ryan Hunt committed
68
include_version = true
69
# An optional namespace to output around the generated bindings
Ryan Hunt's avatar
Ryan Hunt committed
70
namespace = "ffi"
71
# An optional list of namespaces to output around the generated bindings
Ryan Hunt's avatar
Ryan Hunt committed
72
namespaces = ["mozilla", "wr"]
73
# The style to use for curly braces
Ryan Hunt's avatar
Ryan Hunt committed
74
braces = "[SameLine|NextLine]"
75
# The desired length of a line to use when formatting lines
Ryan Hunt's avatar
Ryan Hunt committed
76
line_length = 80
77
# The amount of spaces in a tab
Ryan Hunt's avatar
Ryan Hunt committed
78
tab_width = 2
79
# The language to output bindings in
Ryan Hunt's avatar
Ryan Hunt committed
80
language = "[C|C++]"
81
82
83
84

[parse]
# Whether to parse dependent crates and include their types in the generated
# bindings
Ryan Hunt's avatar
Ryan Hunt committed
85
parse_deps = true
86
# A white list of crate names that are allowed to be parsed
Ryan Hunt's avatar
Ryan Hunt committed
87
include = ["webrender", "webrender_traits"]
88
# A black list of crate names that are not allowed to be parsed
Ryan Hunt's avatar
Ryan Hunt committed
89
exclude = ["libc"]
90
91
# A list of crate names that should be run through `cargo expand` before
# parsing to expand any macros
Ryan Hunt's avatar
Ryan Hunt committed
92
expand = ["euclid"]
93
94
95

[fn]
# An optional prefix to put before every function declaration
Ryan Hunt's avatar
Ryan Hunt committed
96
prefix = "string"
97
# An optional postfix to put after any function declaration
Ryan Hunt's avatar
Ryan Hunt committed
98
postfix = "string"
99
# How to format function arguments
100
args = "[Auto|Vertical|Horizontal]"
101
# A rule to use to rename function argument names
102
rename_args = "[None|GeckoCase|LowerCase|UpperCase|PascalCase|CamelCase|SnakeCase|ScreamingSnakeCase|QualifiedScreamingSnakeCase]"
103
104
105

[struct]
# A rule to use to rename field names
106
rename_fields = "[None|GeckoCase|LowerCase|UpperCase|PascalCase|CamelCase|SnakeCase|ScreamingSnakeCase|QualifiedScreamingSnakeCase]"
107
# Whether to generate helper template specialization for generics
Ryan Hunt's avatar
Ryan Hunt committed
108
generic_template_specialization = true
109
# Whether to derive an operator== for all structs
Ryan Hunt's avatar
Ryan Hunt committed
110
derive_eq = false
111
# Whether to derive an operator!= for all structs
Ryan Hunt's avatar
Ryan Hunt committed
112
derive_neq = false
113
# Whether to derive an operator< for all structs
Ryan Hunt's avatar
Ryan Hunt committed
114
derive_lt = false
115
# Whether to derive an operator<= for all structs
Ryan Hunt's avatar
Ryan Hunt committed
116
derive_lte = false
117
# Whether to derive an operator> for all structs
Ryan Hunt's avatar
Ryan Hunt committed
118
derive_gt = false
119
# Whether to derive an operator>= for all structs
Ryan Hunt's avatar
Ryan Hunt committed
120
derive_gte = false
121
122
123

[enum]
# A rule to use to rename enum variants
124
rename_variants = "[None|GeckoCase|LowerCase|UpperCase|PascalCase|CamelCase|SnakeCase|ScreamingSnakeCase|QualifiedScreamingSnakeCase]"
Ryan Hunt's avatar
Ryan Hunt committed
125

126
```
127

128
129
## Examples

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

132
133
134
135
136
137
138
139
## Major differences between `cbindgen` and `rusty-cheddar`

1. `cbindgen` supports generics
2. `cbindgen` supports C++ output using `enum class` and `template specialization`
3. `cbindgen` supports generating bindings including multiple modules and crates

There may be other differences, but those are the ones that I know of. Please correct me if I misrepresented anything.

Ryan Hunt's avatar
Ryan Hunt committed
140
141
## How it works

Ryan Hunt's avatar
Ryan Hunt committed
142
1. All the structs, unions, enums, type aliases, constants, statics, and functions that are representable in C are gathered
Ryan Hunt's avatar
Ryan Hunt committed
143
2. A dependency graph is built using the extern "C" functions as roots
144
    * This removes unneeded types from the bindings and sorts the structs that depend on each other
Ryan Hunt's avatar
Ryan Hunt committed
145
3. Some code generation is done to specialize generics that are specified as type aliases
146
4. The items are printed in dependency order in C syntax
Ryan Hunt's avatar
Ryan Hunt committed
147
148
149

## Future work

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

## Prominent users
* [milksnake](https://github.com/getsentry/milksnake)
* [webrender](https://searchfox.org/mozilla-central/source/gfx/webrender_bindings/webrender_ffi_generated.h)