1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
# Servo's rust-bindgen
A binding generator for the Rust language.
This is a fork of [crabtw/rust-bindgen](https://github.com/crabtw/rust-bindgen)
designed to work on C++ code as well.
Currently this is being used for Servo's SpiderMonkey bindings, and also for
the [Stylo](https://public.etherpad-mozilla.org/p/stylo) project.
## Requirements
The current generator runs on with clang 3.8, but can also run with clang 3.9
with more features (such as detection of inlined functions).
### Installing clang 3.8
#### OSX
```
# brew install llvm38
```
#### On Debian-based Linuxes
```
# apt-get install llvm-3.8-dev libclang-3.8-dev
```
#### Arch
```
# pacman -S clang clang-tools-extra
```
### Getting clang 3.9
#### From a package manager
Clang 3.9 has ben released about a month ago, and some package managers already
provide it.
For example, for MacPorts:
```
$ port install clang-3.9
$ LIBCLANG_PATH=/opt/local/libexec/llvm-3.9/lib \
LD_LIBRARY_PATH=/opt/local/libexec/llvm-3.9/lib \
cargo build
```
#### From source
If your package manager doesn't yet offer Clang 3.9, you'll need to build from
source. For that, follow the instructions
[here](http://clang.llvm.org/get_started.html).
Those instructions list optional steps. For bindgen:
* Checkout and build clang
* Checkout and build the extra-clang-tools
* Checkout and build the compiler-rt
* You do not need to checkout or build libcxx
## Building
```
$ cargo build --features llvm_stable
```
If you want a build with extra features (llvm 3.9) then you can use:
```
$ LIBCLANG_PATH=path/to/clang-3.9/build/lib \
LD_LIBRARY_PATH=path/to/clang-3.9/build/lib \
cargo build
```
# Command Line Usage
There are a few options documented when running `./bindgen --help`. Other
options might exist (see [the SpiderMonkey script][sm-script] and [the Stylo
scripts][stylo-scripts] to see how is it used inside the Servo organisation.
## C++ Usage
This fork of rust-bindgen can handle a number of C++ features.
When passing in header files, the file will automatically be treated as C++ if
it ends in ``.hpp``. If it doesn't, ``-x c++`` can be used to force C++ mode.
## Annotations
The translation of classes, structs, enums, and typedefs can be adjusted using
annotations. Annotations are specifically formatted html tags inside doxygen
style comments.
### `opaque`
The `opaque` annotation instructs bindgen to ignore all fields defined in
a struct/class.
```cpp
/// <div rustbindgen opaque></div>
```
### `hide`
The `hide` annotation instructs bindgen to ignore the struct/class/field/enum
completely.
```
/// <div rustbindgen hide></div>
```
### `replaces`
The `replaces` annotation can be used to use a type as a replacement for other
(presumably more complex) type. This is used in Stylo to generate bindings for
structures that for multiple reasons are too complex for bindgen to understand.
For example, in a C++ header:
```cpp
/**
* <div rustbindgen replaces="nsTArray"></div>
*/
template<typename T>
class nsTArray_Simple {
T* mBuffer;
public:
// The existence of a destructor here prevents bindgen from deriving the Clone
// trait via a simple memory copy.
~nsTArray_Simple() {};
};
```
That way, after code generation, the bindings for the `nsTArray` type are
the ones that would be generated for `nsTArray_Simple`.
### `nocopy`
The `nocopy` annotation is used to prevent bindgen to autoderive the `Copy`
and `Clone` traits for a type.
# Macro Usage
This mode isn't actively maintained, so no promises are made around it. Check
out the upstream documentation for info about how it *should* work.
[sm-script]: https://github.com/servo/rust-mozjs/blob/master/etc/bindings.sh
[stylo-scripts]: https://github.com/servo/servo/tree/master/ports/geckolib/gecko_bindings/tools
|
