Merge branch 'master' into feature-832-custom-rust-target

Author: tmfink

.travis.yml

@@ -17,15 +17,32 @@ env:
   global:
     - CARGO_TARGET_DIR=/tmp/bindgen
   matrix:
-    - LLVM_VERSION=3.7.1 BINDGEN_FEATURES=testing_only_libclang_3_8
-    - LLVM_VERSION=3.8.1 BINDGEN_FEATURES=testing_only_libclang_3_8
-    - LLVM_VERSION=3.9.0 BINDGEN_FEATURES=testing_only_libclang_3_9
-    - LLVM_VERSION=4.0.0 BINDGEN_FEATURES=testing_only_libclang_4
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="test"         BINDGEN_PROFILE=
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="test"         BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="integration"  BINDGEN_PROFILE=
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="integration"  BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="expectations" BINDGEN_PROFILE=
+    - LLVM_VERSION="3.8.1" BINDGEN_JOB="expectations" BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="test"         BINDGEN_PROFILE=
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="test"         BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="integration"  BINDGEN_PROFILE=
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="integration"  BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="expectations" BINDGEN_PROFILE=
+    - LLVM_VERSION="3.9.0" BINDGEN_JOB="expectations" BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="test"         BINDGEN_PROFILE=
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="test"         BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="test"         BINDGEN_PROFILE=            BINDGEN_FEATURES="testing_only_extra_assertions"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="test"         BINDGEN_PROFILE="--release" BINDGEN_FEATURES="testing_only_extra_assertions"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="integration"  BINDGEN_PROFILE=
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="integration"  BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="expectations" BINDGEN_PROFILE=
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="expectations" BINDGEN_PROFILE="--release"
+    - LLVM_VERSION="4.0.0" BINDGEN_JOB="misc"
 
 matrix:
   fast_finish: true
   allow_failures:
-    - env: LLVM_VERSION=3.7.1 BINDGEN_FEATURES=testing_only_libclang_3_8
+    - env: LLVM_VERSION=4.0.0 BINDGEN_JOB=rustfmt
 
 cache:
   directories:
@@ -35,14 +52,12 @@ cache:
 before_install: . ./ci/before_install.sh
 
 script:
-  # - ./ci/assert-rustfmt.sh
-  - BINDGEN_FEATURES="$BINDGEN_FEATURES" ./ci/assert-docs.sh
-  - BINDGEN_FEATURES="$BINDGEN_FEATURES" ./ci/test.sh
-  - ./ci/test-book.sh
+  - BINDGEN_JOB="$BINDGEN_JOB" BINDGEN_PROFILE="$BINDGEN_PROFILE" BINDGEN_FEATURES="$BINDGEN_FEATURES" ./ci/script.sh
 
 after_success:
   - test "$TRAVIS_PULL_REQUEST" == "false" &&
     test "$TRAVIS_BRANCH" == "master" &&
+    test "$BINDGEN_JOB" == "misc" &&
     ./ci/deploy-book.sh
 
 notifications:

CONTRIBUTING.md

@@ -14,8 +14,9 @@ out to us in a GitHub issue, or stop by
 - [Building](#building)
 - [Testing](#testing)
   - [Overview](#overview)
-  - [Running All Tests](#running-all-tests)
-  - [Running a Single Test](#running-a-single-test)
+  - [Testing Bindings Generation](#testing-bindings-generation)
+  - [Testing Generated Bindings](#testing-generated-bindings)
+  - [Testing a Single Header's Bindings Generation and Compiling its Bindings](#testing-a-single-headers-bindings-generation-and-compiling-its-bindings)
   - [Authoring New Tests](#authoring-new-tests)
   - [Test Expectations and `libclang` Versions](#test-expectations-and-libclang-versions)
 - [Automatic code formatting](#automatic-code-formatting)
@@ -85,38 +86,49 @@ $ cargo build --features testing_only_docs
 
 ## Testing
 
-Code for binding generation and testing thereof is in the `bindgen` crate.
-The following sections assume you are working in that subdirectory.
-
 ### Overview
 
 Input C/C++ test headers reside in the `tests/headers` directory. Expected
-output Rust bindings live in `tests/expectations/tests`.
+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`.
 
-For example, `tests/headers/my_header.h`'s expected generated Rust bindings
-would be `tests/expectations/tests/my_header.rs`.
+There is also the `./bindgen-integration` crate, which uses `bindgen` to
+generate bindings to some C++ code, and then uses the bindings, asserting that
+values are what we expect them to be both on the Rust and C++ side.
 
-Run `cargo test` to compare generated Rust bindings to the expectations.
+### Testing Bindings Generation
 
-### Running All Tests
+To regenerate bindings from the corpus of test headers in `tests/headers` and
+compare them against the expected bindings in `tests/expectations/tests`, run:
 
 ```
-$ cargo test --features testing_only_libclang_$VERSION
+$ cargo test
 ```
 
-Where `$VERSION` is one of:
+As long as you aren't making any changes to `bindgen`'s output, running this
+should be sufficient to test your local modifications.
 
-* `4`
-* `3_9`
-* `3_8`
+### Testing Generated Bindings
 
-depending on which version of `libclang` you have installed.
+If your local changes are introducing expected modifications in the
+`tests/expectations/tests/*` bindings files, then you should test that the
+generated bindings files still compile, and that their struct layout tests still
+pass.
 
-### Running a Single Test
+You can do this with these commands:
 
-To generate bindings for a single test header, compile the bindings, and run the
-layout assertion tests for those bindings, use the `tests/test-one.sh`
-script. It supports fuzzy searching for test headers. For example, to test
+```
+$ cd tests/expectations
+$ cargo test
+```
+
+### Testing a Single Header's Bindings Generation and Compiling its Bindings
+
+Sometimes its useful to work with one test header from start (generating
+bindings for it) to finish (compiling the bindings and running their layout
+tests). This can be done with the `tests/test-one.sh` script. It supports fuzzy
+searching for test headers. For example, to test
 `tests/headers/what_is_going_on.hpp`, execute this command:
 
 ```
@@ -132,14 +144,17 @@ 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:
 
+`new_test_header.hpp`:
+
 ```c
 // bindgen-flags: --enable-cxx-namespaces -- -std=c++14
 ```
 
-Then verify the new Rust bindings compile and pass some basic tests:
+Then verify the new Rust bindings compile and pass their layout tests:
 
 ```
-$ cargo test -p tests_expectations
+$ cd tests/expectations
+$ cargo test new_test_header
 ```
 
 ### Test Expectations and `libclang` Versions
@@ -161,6 +176,22 @@ request, and then when Travis CI fails, it will log a diff of the
 expectations. Use the diff to patch the appropriate expectation file locally and
 then update your pull request.
 
+Usually, `bindgen`'s test runner can infer which version of `libclang` you
+have. If for some reason it can't, you can force a specific `libclang` version
+to check the bindings against with a cargo feature:
+
+```
+$ cargo test --features testing_only_libclang_$VERSION
+```
+
+Where `$VERSION` is one of:
+
+* `4`
+* `3_9`
+* `3_8`
+
+depending on which version of `libclang` you have installed.
+
 ## Automatic code formatting
 
 We use [`rustfmt`](https://github.com/rust-lang-nursery/rustfmt) to enforce a

ci/script.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+set -xeu
+cd "$(dirname "$0")/.."
+
+# Note that `$BINDGEN_PROFILE` is never in quotes so that it expands to nothing
+# (not even an empty string argument) when the variable is empty. This is
+# necessary so we don't pass an unexpected flag to cargo.
+
+export RUST_BACKTRACE=1
+
+case "$BINDGEN_JOB" in
+    "test")
+        cargo test $BINDGEN_PROFILE --features "$BINDGEN_FEATURES"
+        ./ci/assert-no-diff.sh
+        ;;
+
+    "integration")
+        cd ./bindgen-integration
+        cargo test $BINDGEN_PROFILE --features "$BINDGEN_FEATURES"
+        ;;
+
+    "expectations")
+        cd ./tests/expectations
+        cargo test $BINDGEN_PROFILE
+        ;;
+
+    "misc")
+        ./ci/assert-docs.sh
+        ./ci/test-book.sh
+        ./ci/no-includes.sh
+        # `rustfmt` isn't reaching a fixed point on bindgen
+        # code... https://github.com/rust-lang-nursery/rustfmt/issues/1376
+        # ./ci/assert-rustfmt.sh
+        ;;
+
+    *)
+        echo "Error! Unknown \$BINDGEN_JOB: '$BINDGEN_JOB'"
+        exit 1
+esac