src/vendor/compiletest_rs/README.md

   1 compiletest-rs
   2 ==============
   3
   4 This project is an attempt at extracting the `compiletest` utility from the Rust
   5 compiler.
   6
   7 The `compiletest` utility is useful for library and plugin developers, who want
   8 to include test programs that should fail to compile, issue warnings or
   9 otherwise produce compile-time output.
  10
  11
  12 To use in your project
  13 ----------------------
  14 To use `compiletest-rs` in your application, add the following to `Cargo.toml`
  15
  16 ```
  17 [dev-dependencies]
  18 compiletest_rs = "*"
  19 ```
  20
  21 Create a `tests` folder in the root folder of your project. Create a test file
  22 with something like the following:
  23
  24 ```rust
  25 extern crate compiletest_rs as compiletest;
  26
  27 use std::path::PathBuf;
  28
  29 fn run_mode(mode: &'static str) {
  30     let mut config = compiletest::Config::default();
  31
  32     config.mode = mode.parse().expect("Invalid mode");
  33     config.src_base = PathBuf::from(format!("tests/{}", mode));
  34     config.link_deps(); // Populate config.target_rustcflags with dependencies on the path
  35
  36     compiletest::run_tests(&config);
  37 }
  38
  39 #[test]
  40 fn compile_test() {
  41     run_mode("compile-fail");
  42     run_mode("run-pass");
  43 }
  44
  45 ```
  46
  47 Each mode corresponds to a folder with the same name in the `tests` folder. That
  48 is for the `compile-fail` mode the test runner looks for the
  49 `tests/compile-fail` folder.
  50
  51 Adding flags to the Rust compiler is a matter of assigning the correct field in
  52 the config. The most common flag to populate is the
  53 `target_rustcflags` to include the link dependencies on the path.
  54
  55 ```rust
  56 // NOTE! This is the manual way of adding flags
  57 config.target_rustcflags = Some("-L target/debug".to_string());
  58 ```
  59
  60 This is useful (and necessary) for library development. Note that other
  61 secondary library dependencies may have their build artifacts placed in
  62 different (non-obvious) locations and these locations must also be
  63 added.
  64
  65 For convenience, `Config` provides a `link_deps()` method that
  66 populates `target_rustcflags` with all the dependencies found in the
  67 `PATH` variable (which is OS specific). For most cases, it should be
  68 sufficient to do:
  69
  70 ```rust
  71 let mut config = compiletest::Config::default();
  72 config.link_deps();
  73 ```
  74
  75 Example
  76 -------
  77 See the `test-project` folder for a complete working example using the
  78 `compiletest-rs` utility. Simply `cd test-project` and `cargo test` to see the
  79 tests run.
  80
  81 TODO
  82 ----
  83  - The `run-pass` mode is strictly not necessary since it's baked right into
  84    Cargo, but I haven't bothered to take it out