Skip to content

Clean up the README.md and CONTRIBUTING.md docs #408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 19, 2017
Merged

Clean up the README.md and CONTRIBUTING.md docs #408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0409c2c
Clean up the README.md and CONTRIBUTING.md docs
fitzgen Jan 19, 2017
78235aa
Move the building instructions from README.md to CONTRIBUTING.md
fitzgen Jan 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 71 additions & 34 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

* [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)

## Code of Conduct <span id="coc"/>
out to us in a GitHub issue, or stop by
[#servo on irc.mozilla.org](irc://irc.mozilla.org#servo) and introduce yourself.

<!-- 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](#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:
Expand All @@ -33,39 +40,68 @@ issue, provide us with:
* The actual `bindgen` output
* The [debugging logs](#logs) generated when running `bindgen` on this testcase

## Building <span id="building"/>
## Building

To build `libbindgen`:

```
$ cd bindgen/libbindgen
$ cargo build
```

To build the `bindgen` executable:

Build instructions are in the [README](./README.md).
```
$ cd bindgen/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
```

Additionally, you may want to build and test with the `_docs` feature to ensure
Additionally, you may want to build and test with the `docs_` feature to ensure
that you aren't forgetting to document types and functions. CI will catch it if
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,
`tests/headers/my_header.h`'s expected generated Rust bindings would be
`tests/expectations/tests/my_header.rs`.
Input C/C++ test headers reside in the `libbindgen/tests/headers`
directory. Expected output Rust bindings live in
`libbindgen/tests/expectations/tests`. For example,
`libbindgen/tests/headers/my_header.h`'s expected generated Rust bindings would
be `libbindgen/tests/expectations/tests/my_header.rs`.

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
Expand All @@ -84,7 +120,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.
Expand All @@ -105,10 +141,10 @@ $ 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.
`RUST_LOG=libbindgen` to get a bunch of debugging log spew.

```
$ RUST_LOG=libbindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
Expand All @@ -117,10 +153,11 @@ $ RUST_LOG=libbindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
This logging can also be used when debugging failing tests:

```
$ RUST_LOG=libbindgen cd libbindgen && cargo test
$ cd libbindgen
$ RUST_LOG=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`,
Expand Down
112 changes: 66 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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

#### Simple Example: `./bindgen-integration`

# Library usage with `build.rs`
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.

See [the Stylo build script][stylo-script] to see how it is used inside the
Servo organisation.
[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

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -188,7 +208,7 @@ 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.