mirror of
https://gitee.com/openharmony/third_party_rust_bindgen
synced 2024-12-02 12:36:27 +00:00
Clean up the README.md and CONTRIBUTING.md docs
Use the `doctoc` program to generate tables of contents, stop referring to forking and make this the canonical `bindgen`, move the section on building to last.
This commit is contained in:
Nick Fitzgerald
parent
be53b94cae
commit
0409c2cb10
@ -1,28 +1,35 @@
|
||||
# Contributing to `servo/rust-bindgen`
|
||||
# Contributing to `bindgen`
|
||||
|
||||
Hi! We'd love to have your contributions! If you want help or mentorship, reach
|
||||
out to us in a GitHub issue, or stop by #servo on irc.mozilla.org and introduce
|
||||
yourself.
|
||||
out to us in a GitHub issue, or stop by
|
||||
[#servo on irc.mozilla.org](irc://irc.mozilla.org#servo) and introduce yourself.
|
||||
|
||||
* [Code of Conduct](#coc)
|
||||
* [Filing an Issue](#issue)
|
||||
* [Building](#building)
|
||||
* [Testing](#tests)
|
||||
* [Overview](#tests-overview)
|
||||
* [Running All Tests](#tests-all)
|
||||
* [Running a Single, Specific Test](#tests-one)
|
||||
* [Authoring New Tests](#tests-new)
|
||||
* [Automatic Code Formatting](#formatting)
|
||||
* [Debug Logging](#logs)
|
||||
* [Using `creduce` to Minimize Test Cases](#creduce)
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
## Code of Conduct <span id="coc"/>
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Filing an Issue](#filing-an-issue)
|
||||
- [Building](#building)
|
||||
- [Testing](#testing)
|
||||
- [Overview](#overview)
|
||||
- [Running All Tests](#running-all-tests)
|
||||
- [Authoring New Tests](#authoring-new-tests)
|
||||
- [Automatic code formatting](#automatic-code-formatting)
|
||||
- [Debug Logging](#debug-logging)
|
||||
- [Using `creduce` to Minimize Test Cases](#using-creduce-to-minimize-test-cases)
|
||||
- [Isolating Your Test Case](#isolating-your-test-case)
|
||||
- [Writing a Predicate Script](#writing-a-predicate-script)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
We abide by the [Rust Code of Conduct][coc] and ask that you do as well.
|
||||
|
||||
[coc]: https://www.rust-lang.org/en-US/conduct.html
|
||||
|
||||
## Filing an Issue <span id="issue"/>
|
||||
## Filing an Issue
|
||||
|
||||
Think you've found a bug? File an issue! To help us understand and reproduce the
|
||||
issue, provide us with:
|
||||
@ -33,7 +40,7 @@ issue, provide us with:
|
||||
* The actual `bindgen` output
|
||||
* The [debugging logs](#logs) generated when running `bindgen` on this testcase
|
||||
|
||||
## Building <span id="building"/>
|
||||
## Building
|
||||
|
||||
Build instructions are in the [README](./README.md).
|
||||
|
||||
@ -45,12 +52,12 @@ you forget, but the turn around will be a lot slower ;)
|
||||
$ cd libbindgen && cargo build --features "llvm_stable _docs"
|
||||
```
|
||||
|
||||
## Testing <span id="tests"/>
|
||||
## Testing
|
||||
|
||||
Code for binding generation and testing thereof is in the `libbindgen` crate.
|
||||
The following sections assume you are working in that subdirectory.
|
||||
|
||||
### Overview <span id="tests-overview"/>
|
||||
### Overview
|
||||
|
||||
Input C/C++ test headers reside in the `tests/headers` directory. Expected
|
||||
output Rust bindings live in `tests/expectations/tests`. For example,
|
||||
@ -59,13 +66,13 @@ output Rust bindings live in `tests/expectations/tests`. For example,
|
||||
|
||||
Run `cargo test` to compare generated Rust bindings to the expectations.
|
||||
|
||||
### Running All Tests <span id="tests-all"/>
|
||||
### Running All Tests
|
||||
|
||||
```
|
||||
$ cargo test [--features llvm_stable]
|
||||
```
|
||||
|
||||
### Authoring New Tests <span id="tests-new"/>
|
||||
### Authoring New Tests
|
||||
|
||||
To add a new test header to the suite, simply put it in the `tests/headers`
|
||||
directory. Next, run `bindgen` to generate the initial expected output Rust
|
||||
@ -84,7 +91,7 @@ Then verify the new Rust bindings compile and pass some basic tests:
|
||||
$ cargo test -p tests_expectations
|
||||
```
|
||||
|
||||
## Automatic code formatting <span id="formatting"/>
|
||||
## Automatic code formatting
|
||||
|
||||
There's a `rustfmt.toml` file in the repo. Ideally changes should be consistent
|
||||
with the style, though that's not enforced right now.
|
||||
@ -105,7 +112,7 @@ $ cargo install rustfmt
|
||||
|
||||
And ensure `~/.cargo/bin` is on your path.
|
||||
|
||||
## Debug Logging <span id="logs"/>
|
||||
## Debug Logging
|
||||
|
||||
To help debug what `bindgen` is doing, you can define the environment variable
|
||||
`RUST_LOG=bindgen` to get a bunch of debugging log spew.
|
||||
@ -120,7 +127,7 @@ This logging can also be used when debugging failing tests:
|
||||
$ RUST_LOG=libbindgen cd libbindgen && cargo test
|
||||
```
|
||||
|
||||
## Using `creduce` to Minimize Test Cases <span id="creduce"/>
|
||||
## Using `creduce` to Minimize Test Cases
|
||||
|
||||
If you are hacking on `bindgen` and find a test case that causes an unexpected
|
||||
panic, results in bad Rust bindings, or some other incorrectness in `bindgen`,
|
||||
|
||||
133
README.md
133
README.md
@ -1,38 +1,63 @@
|
||||
# Servo's rust-bindgen
|
||||
# `bindgen`
|
||||
|
||||
A binding generator for the Rust language.
|
||||
Automatically generates Rust FFI bindings to C and C++ libraries.
|
||||
|
||||
This is a fork of [crabtw/rust-bindgen](https://github.com/crabtw/rust-bindgen)
|
||||
designed to work on C++ code as well.
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
|
||||
Currently this is being used for Servo's SpiderMonkey bindings, and also for
|
||||
the [Stylo](https://public.etherpad-mozilla.org/p/stylo) project.
|
||||
|
||||
## Requirements
|
||||
- [Usage](#usage)
|
||||
- [Requirements](#requirements)
|
||||
- [Installing Clang 3.9](#installing-clang-39)
|
||||
- [Windows](#windows)
|
||||
- [OSX](#osx)
|
||||
- [Debian-based Linuxes](#debian-based-linuxes)
|
||||
- [Arch](#arch)
|
||||
- [From source](#from-source)
|
||||
- [Library usage with `build.rs`](#library-usage-with-buildrs)
|
||||
- [`build.rs` Tutorial](#buildrs-tutorial)
|
||||
- [Simple Example: `./bindgen-integration`](#simple-example-bindgen-integration)
|
||||
- [Real World Example: Stylo](#real-world-example-stylo)
|
||||
- [Command Line Usage](#command-line-usage)
|
||||
- [C++](#c)
|
||||
- [Annotations](#annotations)
|
||||
- [`opaque`](#opaque)
|
||||
- [`hide`](#hide)
|
||||
- [`replaces`](#replaces)
|
||||
- [`nocopy`](#nocopy)
|
||||
- [Building From Source](#building-from-source)
|
||||
|
||||
It is recommended to use clang 3.9 with the current generator. It can run with
|
||||
clang 3.8 with some features disabled.
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
### Installing Clang 3.9
|
||||
## Usage
|
||||
|
||||
#### Windows
|
||||
### Requirements
|
||||
|
||||
It is recommended to use Clang 3.9 or greater, however `bindgen` can run with
|
||||
older Clangs with some features disabled.
|
||||
|
||||
#### Installing Clang 3.9
|
||||
|
||||
##### Windows
|
||||
|
||||
Download and install the official pre-built binary from
|
||||
[LLVM download page](http://releases.llvm.org/download.html).
|
||||
|
||||
#### OSX
|
||||
##### OSX
|
||||
|
||||
If you use Homebrew:
|
||||
|
||||
```
|
||||
$ brew install llvm
|
||||
```
|
||||
|
||||
If you use MacPorts:
|
||||
|
||||
```
|
||||
$ port install clang-3.9
|
||||
```
|
||||
|
||||
#### Debian-based Linuxes
|
||||
##### Debian-based Linuxes
|
||||
|
||||
```
|
||||
# apt-get install llvm-3.9-dev libclang-3.9-dev
|
||||
@ -42,13 +67,13 @@ Ubuntu 16.10 provides the necessary packages directly. If you are using older
|
||||
version of Ubuntu or other Debian-based distros, you may need to add the LLVM
|
||||
repos to get version 3.9. See http://apt.llvm.org/.
|
||||
|
||||
#### Arch
|
||||
##### Arch
|
||||
|
||||
```
|
||||
# pacman -S clang
|
||||
```
|
||||
|
||||
#### From source
|
||||
##### 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
|
||||
@ -61,31 +86,26 @@ Those instructions list optional steps. For bindgen:
|
||||
* Checkout and build the compiler-rt
|
||||
* You do not need to checkout or build libcxx
|
||||
|
||||
## Building
|
||||
### Library usage with `build.rs`
|
||||
|
||||
```
|
||||
$ cd bindgen
|
||||
$ cargo build
|
||||
```
|
||||
#### `build.rs` Tutorial
|
||||
|
||||
If you installed multiple versions of llvm, it may not be able to locate the
|
||||
latest version of libclang. In that case, you may want to either uninstall
|
||||
other versions of llvm, or specify the path of the desired libclang explicitly:
|
||||
```
|
||||
$ export LIBCLANG_PATH=path/to/clang-3.9/lib
|
||||
```
|
||||
[Here is a step-by-step tutorial for generating FFI bindings to the `bzip2` C library.][tutorial]
|
||||
|
||||
On Linux and macOS, you may also need to add a path to `libclang.so` (usually
|
||||
the same path as above) to library search path. This can be done as below:
|
||||
```
|
||||
$ export LD_LIBRARY_PATH=path/to/clang-3.9/lib # for Linux
|
||||
$ export DYLD_LIBRARY_PATH=path/to/clang-3.9/lib # for macOS
|
||||
```
|
||||
[tutorial]: http://fitzgeraldnick.com/2016/12/14/using-libbindgen-in-build-rs.html
|
||||
|
||||
# Library usage with `build.rs`
|
||||
#### Simple Example: `./bindgen-integration`
|
||||
|
||||
See [the Stylo build script][stylo-script] to see how it is used inside the
|
||||
Servo organisation.
|
||||
The [`./bindgen-integration`][integration] directory has an example crate that
|
||||
generates FFI bindings in `build.rs` and can be used a template for new
|
||||
projects.
|
||||
|
||||
[integration]: ./bindgen-integration
|
||||
|
||||
#### Real World Example: Stylo
|
||||
|
||||
A real world example is [the Stylo build script][stylo-script] used for
|
||||
integrating Servo's layout system into Gecko.
|
||||
|
||||
[stylo-script]: https://github.com/servo/servo/blob/master/components/style/build_gecko.rs
|
||||
|
||||
@ -124,28 +144,28 @@ In `src/main.rs`:
|
||||
include!(concat!(env!("OUT_DIR"), "/example.rs"));
|
||||
```
|
||||
|
||||
# Command Line Usage
|
||||
### Command Line Usage
|
||||
|
||||
There are a few options documented when running `./bindgen --help`. Other
|
||||
options might exist (see [the SpiderMonkey script][sm-script] to see how it
|
||||
is used inside the Servo organisation.
|
||||
```
|
||||
$ cargo install bindgen
|
||||
```
|
||||
|
||||
[sm-script]: https://github.com/servo/rust-mozjs/blob/master/etc/bindings.sh
|
||||
There are a few options documented when running `./bindgen --help`.
|
||||
|
||||
## C++ Usage
|
||||
### C++
|
||||
|
||||
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
|
||||
### 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`
|
||||
#### `opaque`
|
||||
|
||||
The `opaque` annotation instructs bindgen to ignore all fields defined in
|
||||
a struct/class.
|
||||
@ -154,7 +174,7 @@ a struct/class.
|
||||
/// <div rustbindgen opaque></div>
|
||||
```
|
||||
|
||||
### `hide`
|
||||
#### `hide`
|
||||
|
||||
The `hide` annotation instructs bindgen to ignore the struct/class/field/enum
|
||||
completely.
|
||||
@ -163,7 +183,7 @@ completely.
|
||||
/// <div rustbindgen hide></div>
|
||||
```
|
||||
|
||||
### `replaces`
|
||||
#### `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
|
||||
@ -188,7 +208,28 @@ public:
|
||||
That way, after code generation, the bindings for the `nsTArray` type are
|
||||
the ones that would be generated for `nsTArray_Simple`.
|
||||
|
||||
### `nocopy`
|
||||
#### `nocopy`
|
||||
|
||||
The `nocopy` annotation is used to prevent bindgen to autoderive the `Copy`
|
||||
and `Clone` traits for a type.
|
||||
|
||||
## Building From Source
|
||||
|
||||
```
|
||||
$ cd bindgen
|
||||
$ cargo build
|
||||
```
|
||||
|
||||
If you installed multiple versions of llvm, it may not be able to locate the
|
||||
latest version of libclang. In that case, you may want to either uninstall
|
||||
other versions of llvm, or specify the path of the desired libclang explicitly:
|
||||
```
|
||||
$ export LIBCLANG_PATH=path/to/clang-3.9/lib
|
||||
```
|
||||
|
||||
On Linux and macOS, you may also need to add a path to `libclang.so` (usually
|
||||
the same path as above) to library search path. This can be done as below:
|
||||
```
|
||||
$ export LD_LIBRARY_PATH=path/to/clang-3.9/lib # for Linux
|
||||
$ export DYLD_LIBRARY_PATH=path/to/clang-3.9/lib # for macOS
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user