Skip to content
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

Jump to bottom

Split off bindgen library into a sub-crate #204

Merged
merged 3 commits into from
Nov 15, 2016
Merged

Split off bindgen library into a sub-crate #204

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8270a0c
Transition to libbindgen sub-crate
jdub Nov 15, 2016
c555fcf
Document library usage
jdub Nov 15, 2016
073b12f
Remove plugin and its documentation
jdub Nov 15, 2016
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
4 changes: 0 additions & 4 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
bindgen
libbindgen*

# Cargo
target/
Cargo.lock
*~
#*#

7 changes: 5 additions & 2 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,19 @@ cache:

before_install: . ./ci/before_install.sh

before_script: cd libbindgen

script:
- cargo build --verbose --features "$BINDGEN_FEATURES"
- cargo test --features "$BINDGEN_FEATURES"
- cargo build --release --verbose --features "$BINDGEN_FEATURES"
- cargo test --release --features "$BINDGEN_FEATURES"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems travis will no longer build bindgen executable.
Would it make sense to not cd in libbindgen and do something along the line of(if that works):

/// Build library and tests:
cargo test -p libbindgen --features "$BINDGEN_FEATURES"
cargo test -p libbindgen --release --features "$BINDGEN_FEATURES"
cargo build -p libbindgen --features "$BINDGEN_FEATURES _docs"

/// build executable and test (even though we don't really have any test for the executable)
cargo test --features "$BINDGEN_FEATURES"
cargo build --features "$BINDGEN_FEATURES _docs"

/// Verify the expectations build
cargo test -p tests_expectations <<<<- still need to describe this as a dev dependency of bidgen cargo.toml

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do like this idea, though there's some weirdness going on. What is a "package" to cargo test?

  • clap is a direct dependency of bindgen (which I had already built, as it happens)
  • clap is a dev-dependency of the libbindgen crate
jdub@sel4:/tmp/rust-bindgen$ cargo test --features llvm_stable -p libbindgen
   Compiling libbindgen v0.17.0 (file:///tmp/rust-bindgen/libbindgen)
error[E0463]: can't find crate for `clap`
 --> libbindgen/tests/tests.rs:1:1
  |
1 | extern crate clap;
  | ^^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to previous error

error: Could not compile `libbindgen`.

To learn more, run the command again with --verbose.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we definitely should be building the binary in CI at least.

Copy link
Member

@fitzgen fitzgen Nov 14, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One more +1 to building the binary in CI: we need to ensuring that master always has a compiling binary; this is a very minimal standard we need to hold ourselves to, and it shouldn't be hard.

- git add -A
- git diff @
- git diff-index --quiet HEAD
- cargo test -p tests_expectations
- cargo build --features "$BINDGEN_FEATURES _docs"
- cd ..
- cargo test --features "$BINDGEN_FEATURES"
- cargo test --release --features "$BINDGEN_FEATURES"

notifications:
webhooks: http://build.servo.org:54856/travis
48 changes: 14 additions & 34 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,46 +42,34 @@ 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 ;)

```
$ cargo build --features "llvm_stable _docs"
$ cd libbindgen && cargo build --features "llvm_stable _docs"
```

## Testing <span id="tests"/>

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"/>

Input C/C++ test headers reside in the `tests/headers` directory. The expected
output rust bindings live in `tests/expectations/tests`; for example,
`tests/headers/my_header.h`'s expected generated rust bindings would be
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`.

The `tests/tools/run-bindgen.py` script runs `bindgen` on the test headers and
compares the results to the expectations.
Run `cargo test` to compare generated Rust bindings to the expectations.

### Running All Tests <span id="tests-all"/>

```
$ cargo test [--features llvm_stable]
```

This spawns a `tests/tools/run-bindgen.py` subprocess for each test header.

### Running a Single, Specific Test <span id="tests-one"/>

```
$ ./tests/tools/run-bindgen.py ./target/debug/bindgen ./tests/headers/some_header.h
```

To learn more about the options available with `run-bindgen.py`:

```
$ ./tests/tools/run-bindgen.py --help
```

### Authoring New Tests <span id="tests-new"/>

To add a new test header to the suite, simply put it in the `tests/headers`
directory. Next, run the `run-bindgen.py` script with the new test header, which
will generate the initial expected output rust bindings.
directory. Next, run `bindgen` to generate the initial expected output Rust
bindings. Put those in `tests/expectations/tests`.

If your new test requires certain flags to be passed to `bindgen`, you can
specify them at the top of the test header, with a comment like this:
Expand All @@ -90,14 +78,7 @@ specify them at the top of the test header, with a comment like this:
// bindgen-flags: --enable-cxx-namespaces -- -std=c++14
```

If your new test requires `bindgen` to be built with certain features, you can
specify the required features at the top of the test header in a similar manner:

```c
// bingden-features: llvm_stable
```

Then verify the new rust bindings compile and its tests pass:
Then verify the new Rust bindings compile and pass some basic tests:

```
$ cargo test -p tests_expectations
Expand Down Expand Up @@ -130,14 +111,13 @@ 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=bindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
$ RUST_LOG=libbindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
```

This logging can also be used when debugging failing tests under
`run-bindgen.py`:
This logging can also be used when debugging failing tests:

```
$ RUST_LOG=bindgen ./tests/tools/run-bindgen.py ./target/debug/bindgen tests/headers/whatever.h
$ RUST_LOG=libbindgen cd libbindgen && cargo test
```

## Using `creduce` to Minimize Test Cases <span id="creduce"/>
Expand Down
42 changes: 2 additions & 40 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ authors = [
"Emilio Cobos Álvarez <ecoal95@gmail.com>",
"The Servo project developers",
]
build = "build.rs"
description = "A binding generator for Rust"
homepage = "https://github.com/servo/rust-bindgen"
keywords = ["bindings", "ffi", "code-generation"]
Expand All @@ -14,50 +13,13 @@ readme = "README.md"
repository = "https://github.com/servo/rust-bindgen"
version = "0.17.0"

[[bin]]
doc = false
name = "bindgen"

[build-dependencies]
quasi_codegen = "0.20"

[dependencies]
cfg-if = "0.1.0"
clang-sys = "0.8.0"
clap = "2"
lazy_static = "0.1.*"
libc = "0.2"
libbindgen = { path = "libbindgen" }
log = "0.3"
env_logger = "0.3"
rustc-serialize = "0.3.19"
syntex_syntax = "0.44"
regex = "0.1"
cexpr = "0.2"

[dependencies.aster]
features = ["with-syntex"]
version = "0.28"

[dependencies.clippy]
optional = true
version = "*"

[dependencies.quasi]
features = ["with-syntex"]
version = "0.20"

[features]
llvm_stable = []
static = []
# This feature only exists for CI -- don't use it!
_docs = []

[lib]
name = "bindgen"
path = "src/lib.rs"

[dev-dependencies.tests_expectations]
path = "tests/expectations"

[[test]]
name = "tests"
llvm_stable = ["libbindgen/llvm_stable"]
34 changes: 0 additions & 34 deletions Makefile
View file
Open in desktop

This file was deleted.

42 changes: 34 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,40 @@ $ LIBCLANG_PATH=path/to/clang-3.9/build/lib \
cargo build
```

# Library usage with `build.rs`

In `Cargo.toml`:

```toml
[package]
...
build = "build.rs"

[build-dependencies.libbindgen]
git = "https://github.com/servo/rust-bindgen"
features = ["llvm_stable"]
```

In `build.rs`:

```rust
extern crate libbindgen;

fn main() {
let _ = libbindgen::builder()
.header("example.h")
.use_core()
.generate().unwrap()
.write_to_file(concat!(env!("OUT_DIR"), "/example.rs"));
}
```

In `src/main.rs`:

```rust
include!(concat!(env!("OUT_DIR"), "/example.rs"));
```

# Command Line Usage

There are a few options documented when running `./bindgen --help`. Other
Expand Down Expand Up @@ -142,11 +176,3 @@ the ones that would be generated for `nsTArray_Simple`.

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/components/style/binding_tools
20 changes: 0 additions & 20 deletions bindgen_plugin/Cargo.toml
View file
Open in desktop

This file was deleted.

Loading