Skip to content

Commit 483e02e

Browse files
author
bors-servo
authored
Auto merge of rust-lang#9 - emilio:docs, r=Ms2ger
readme: Add a bit more up-to-date information. r? @nox or @Ms2ger
2 parents e441c20 + 3f91669 commit 483e02e

File tree

1 file changed

+82
-124
lines changed

1 file changed

+82
-124
lines changed

‎README.md

+82-124
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,121 @@
1-
rust-bindgen
2-
============
3-
[![][crates-version-shield]](https://crates.io/crates/bindgen)
4-
[![][crates-downloads-shield]](https://crates.io/crates/bindgen)
5-
[![][crates-license-shield]](https://github.com/crabtw/rust-bindgen/blob/master/LICENSE)
6-
[![][travis-status-shield]](https://travis-ci.org/crabtw/rust-bindgen/)
1+
# Servo's rust-bindgen
72

8-
A binding generator for the rust language.
9-
This is a fork designed to work on Spidermonkey headers.
10-
It is ported from [clay's bindgen][].
3+
A binding generator for the Rust language.
114

12-
Requirements
13-
------------
5+
This is a fork of [crabtw/rust-bindgen](https://github.com/crabtw/rust-bindgen)
6+
designed to work on C++ code as well.
147

15-
* clang 3.7 with patches https://github.com/michaelwu/clang/tree/release_37_smhacks or clang 3.8+
8+
Currently this is being used for Servo's SpiderMonkey bindings, and also for
9+
the [Stylo](https://public.etherpad-mozilla.org/p/stylo) project.
1610

17-
This bindgen fork requires a patched clang or clang 3.8+ to work properly. This is one way to build a patched clang:
18-
```
19-
git clone https://github.com/llvm-mirror/llvm
20-
cd llvm
21-
git checkout release_37
22-
cd tools
23-
git clone https://github.com/llvm-mirror/clang
24-
cd clang
25-
git remote add mwu https://github.com/michaelwu/clang
26-
git fetch mwu
27-
git checkout release_37_smhacks
28-
cd ../.. # llvm root dir
29-
mkdir build
30-
cd build
31-
../configure --enable-optimized
32-
make
33-
```
34-
35-
Then before building, make sure to export the path to this copy of clang:
11+
## Requirements
3612

37-
export LIBCLANG_PATH=~/llvm/build/Release+Asserts/lib
13+
The current generator runs on with clang 3.8, but can also run with clang 3.9
14+
with more features (such as detection of inlined functions).
3815

39-
This path also needs to be set in LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (OSX) when running bindgen.
16+
### Installing clang 3.8
4017

41-
Building
42-
--------
18+
#### OSX
4319

44-
$ cargo build
20+
```
21+
# brew install llvm38
22+
```
4523

46-
Note: This links with Apple's version of libclang on OS X by default. This can be changed by setting the LIBCLANG_PATH environment variable.
24+
#### On Debian-based Linuxes
4725

48-
If you are running the command line tool you will also need to append this
49-
path to your DYLD_LIBRARY_PATH environment variable, which you might already have set if you have installed the Rust compiler outside of standard /usr/local path.
26+
```
27+
# apt-get install llvm-3.8-dev libclang-3.8-dev
28+
```
5029

51-
The default path on OS X is:
30+
#### Arch
5231

53-
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/
32+
```
33+
# pacman -S clang clang-tools-extra
34+
```
5435

55-
Or if you only have Xcode Command Line Tools installed:
36+
## Building
5637

57-
export DYLD_LIBRARY_PATH=/Library/Developer/CommandLineTools/usr/lib
38+
```
39+
$ cargo build --features llvm_stable
40+
```
5841

59-
Command Line Usage
60-
------------------
42+
If you want a build with extra features (llvm 3.9) then you can just use:
6143

6244
```
63-
Usage: ./bindgen [options] input.h
64-
Options:
65-
-h or --help Display help message
66-
-l <name> or -l<name> Link to a dynamic library, can be provided
67-
multiple times
68-
-static-link <name> Link to a static library
69-
-framework-link <name> Link to a framework
70-
-o <output.rs> Write bindings to <output.rs> (default stdout)
71-
-match <name> Only output bindings for definitions from files
72-
whose name contains <name>
73-
If multiple -match options are provided, files
74-
matching any rule are bound to
75-
-builtins Output bindings for builtin definitions
76-
(for example __builtin_va_list)
77-
-allow-unknown-types Don't fail if we encounter types we do not support,
78-
instead treat them as void
79-
-emit-clang-ast Output the ast (for debugging purposes)
80-
-override-enum-type <type> Override enum type, type name could be
81-
uchar
82-
schar
83-
ushort
84-
sshort
85-
uint
86-
sint
87-
ulong
88-
slong
89-
ulonglong
90-
slonglong
91-
92-
Options other than stated above are passed to clang
45+
$ cargo build
9346
```
9447

95-
C++ Usage
96-
---------
97-
This fork of rust-bindgen can handle a number of C++ features. Because it currently uses a fork of clang though, it may require adding extra arguments to find certain headers. On OpenSUSE 13.2, these additional include pathes can be used:
48+
# Command Line Usage
9849

99-
-isystem /usr/lib64/gcc/x86_64-suse-linux/4.8/include -isystem /usr/lib64/gcc/x86_64-suse-linux/4.8/include-fixed
50+
There are a few options documented when running `./bindgen --help`. Other
51+
options might exist (see [the SpiderMonkey script][sm-script] and [the Stylo
52+
scripts][stylo-scripts] to see how is it used inside the Servo organisation.
10053

101-
On OSX, this include path seems to work:
54+
## C++ Usage
10255

103-
-isystem /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/v1
56+
This fork of rust-bindgen can handle a number of C++ features.
10457

105-
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.
58+
When passing in header files, the file will automatically be treated as C++ if
59+
it ends in ``.hpp``. If it doesn't, ``-x c++`` can be used to force C++ mode.
10660

107-
Annotations
108-
-----------
109-
The translation of classes, structs, enums, and typedefs can be adjusted using annotations. Annotations are specifically formatted html tags inside doxygen style comments. The opaque annotation instructs bindgen to ignore all fields defined in a struct/class.
61+
## Annotations
11062

111-
/// <div rustbindgen opaque></div>
63+
The translation of classes, structs, enums, and typedefs can be adjusted using
64+
annotations. Annotations are specifically formatted html tags inside doxygen
65+
style comments.
11266

113-
The hide annotation instructs bindgen to ignore the struct/class/field/enum completely.
67+
### `opaque`
11468

115-
/// <div rustbindgen hide></div>
69+
The `opaque` annotation instructs bindgen to ignore all fields defined in
70+
a struct/class.
11671

117-
Macro Usage
118-
-----------
119-
120-
```
121-
Usage: bindgen!([headers], [named options])
122-
Options:
123-
124-
Option Name Type Default
125-
----------------------------------------------
126-
link multiple strings
127-
link_static multiple strings
128-
link_framework multiple strings
129-
match multiple strings
130-
emit_builtins bool true
131-
allow_unknown_types bool false
132-
clang_args string
72+
```cpp
73+
/// <div rustbindgen opaque></div>
13374
```
134-
See "Command Line Usage" section for option descriptions
13575

136-
Examples
137-
--------
76+
### `hide`
13877

139-
###Generate MySQL client bindings
78+
The `hide` annotation instructs bindgen to ignore the struct/class/field/enum
79+
completely.
14080

141-
bindgen -l mysql -match mysql.h -o mysql.rs /usr/include/mysql/mysql.h
142-
143-
*or*
81+
```
82+
/// <div rustbindgen hide></div>
83+
```
14484

145-
echo '#include <mysql.h>' > gen.h
146-
bindgen `mysql_config --cflags` -l mysql -match mysql.h -o mysql.rs gen.h
85+
### `replaces`
86+
87+
The `replaces` annotation can be used to use a type as a replacement for other
88+
(presumably more complex) type. This is used in Stylo to generate bindings for
89+
structures that for multiple reasons are too complex for bindgen to understand.
90+
91+
For example, in a C++ header:
92+
93+
```cpp
94+
/**
95+
* <div rustbindgen replaces="nsTArray"></div>
96+
*/
97+
template<typename T>
98+
class nsTArray_Simple {
99+
T* mBuffer;
100+
public:
101+
// The existence of a destructor here prevents bindgen from deriving the Clone
102+
// trait via a simple memory copy.
103+
~nsTArray_Simple() {};
104+
};
105+
```
147106
148-
*or*
107+
That way, after code generation, the bindings for the `nsTArray` type are
108+
the ones that would be generated for `nsTArray_Simple`.
149109
150-
Cargo.toml
110+
### `nocopy`
151111
152-
[dependencies.bindgen]
153-
git = "https://github.com/crabtw/rust-bindgen.git"
112+
The `nocopy` annotation is used to prevent bindgen to autoderive the `Copy`
113+
and `Clone` traits for a type.
154114
155-
main.rs
115+
# Macro Usage
156116
157-
#![feature(phase)]
158-
#[phase(plugin)] extern crate bindgen;
117+
This mode isn't actively maintained, so no promises are made around it. Check
118+
out the upstream documentation for info about how it *should* work.
159119
160-
#[allow(dead_code, uppercase_variables, non_camel_case_types)]
161-
mod mysql_bindings {
162-
bindgen!("/usr/include/mysql/mysql.h", match="mysql.h", link="mysql")
163-
}
120+
[sm-script]: https://github.com/servo/rust-mozjs/blob/master/etc/bindings.sh
121+
[stylo-scripts]: https://github.com/servo/servo/tree/master/ports/geckolib/gecko_bindings/tools

0 commit comments

Comments
 (0)