|
1 | | -# Usage |
| 1 | +# Using Kani |
2 | 2 |
|
3 | 3 | At present, Kani can used in two ways: |
4 | | - * [On a single file](./kani-single-file.md) with the `kani` command. |
5 | | - * [On a package](./cargo-kani.md) with the `cargo-kani` command. |
6 | 4 |
|
7 | | -Running [Kani on a single file](./kani-single-file.md) is quite useful for small |
8 | | -examples or projects that don't use `cargo`. |
| 5 | + * [On a single crate](#usage-on-a-single-crate) with the `kani` command. |
| 6 | + * [On a Cargo package](#usage-on-a-package) with the `cargo kani` command. |
9 | 7 |
|
10 | | -However, if you plan to integrate Kani in your projects, the recommended |
11 | | -approach is to use [Kani on a package](./cargo-kani.md) because of its ability |
12 | | -to handle external dependencies. |
| 8 | +If you plan to integrate Kani in your projects, the recommended approach is to use `cargo kani`. |
| 9 | +If you're already using cargo, this will handle dependencies automatically, and it can be configured (if needed) in `Cargo.toml`. |
| 10 | +But `kani` is useful for small examples/tests. |
| 11 | + |
| 12 | +## Usage on a package |
| 13 | + |
| 14 | +Kani is integrated with `cargo` and can be invoked from a package as follows: |
| 15 | + |
| 16 | +```bash |
| 17 | +cargo kani [OPTIONS] |
| 18 | +``` |
| 19 | + |
| 20 | +This works like `cargo test` except that it will analyze all proof harnesses instead of running all test harnesses. |
| 21 | + |
| 22 | +## Common command line flags |
| 23 | + |
| 24 | +Common to both `kani` and `cargo kani` are many command-line flags: |
| 25 | + |
| 26 | + * `--visualize`: Generates an HTML report showing coverage information and providing traces (i.e., counterexamples) for each failure found by Kani. |
| 27 | + |
| 28 | + * `--tests`: Build in "[test mode](https://doc.rust-lang.org/rustc/tests/index.html)", i.e. with `cfg(test)` set and `dev-dependencies` available (when using `cargo kani`). |
| 29 | + |
| 30 | + * `--harness <name>`: By default, Kani checks all proof harnesses it finds. |
| 31 | + You can switch to checking a single harness using this flag. |
| 32 | + |
| 33 | + * `--default-unwind <n>`: Set a default global upper [loop unwinding](./tutorial-loop-unwinding.md) bound for proof harnesses. |
| 34 | + This can force termination when CBMC tries to unwind loops indefinitely. |
| 35 | + |
| 36 | +Run `cargo kani --help` to see a complete list of arguments. |
| 37 | + |
| 38 | +## Usage on a single crate |
| 39 | + |
| 40 | +For small examples or initial learning, it's very common to run Kani on just one source file. |
| 41 | +The command line format for invoking Kani directly is the following: |
| 42 | + |
| 43 | +``` |
| 44 | +kani filename.rs [OPTIONS] |
| 45 | +``` |
| 46 | + |
| 47 | +This will build `filename.rs` and run all proof harnesses found within. |
| 48 | + |
| 49 | +## Configuration in `Cargo.toml` |
| 50 | + |
| 51 | +Users can add a default configuration to the `Cargo.toml` file for running harnesses in a package. |
| 52 | +Kani will extract any arguments from these sections: |
| 53 | + |
| 54 | + * `[workspace.metadata.kani.flags]` |
| 55 | + * `[package.metadata.kani.flags]` |
| 56 | + |
| 57 | +For example, if you want to set a default loop unwinding bound (when it's not otherwise specified), you can achieve this by adding the following lines to the package's `Cargo.toml`: |
| 58 | + |
| 59 | +```toml |
| 60 | +[package.metadata.kani.flags] |
| 61 | +default-unwind = 1 |
| 62 | +``` |
| 63 | + |
| 64 | +The options here are the same as on the command line (`cargo kani --help`), and flags (that is, command line arguments that don't take a value) are enabled by setting them to `true`. |
| 65 | + |
| 66 | +## The build process |
| 67 | + |
| 68 | +When Kani builds your code, it does two important things: |
| 69 | + |
| 70 | +1. It sets `cfg(kani)`. |
| 71 | +2. It injects the `kani` crate. |
| 72 | + |
| 73 | +A proof harness (which you can [learn more about in the tutorial](./kani-tutorial.md)), is a function annotated with `#[kani::proof]` much like a test is annotated with `#[test]`. |
| 74 | +But you may experience a similar problem using Kani as you would with `dev-dependencies`: if you try writing `#[kani::proof]` directly in your code, `cargo build` will fail because it doesn't know what the `kani` crate is. |
| 75 | + |
| 76 | +This is why we recommend the same conventions as are used when writing tests in Rust: wrap your proof harnesses in `cfg(kani)` conditional compilation: |
| 77 | + |
| 78 | +```rust |
| 79 | +#[cfg(kani)] |
| 80 | +mod verification { |
| 81 | + use super::*; |
| 82 | + |
| 83 | + #[kani::proof] |
| 84 | + pub fn check_something() { |
| 85 | + // .... |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +This will ensure that a normal build of your code will be completely unaffected by anything Kani-related. |
| 91 | + |
| 92 | +This conditional compilation with `cfg(kani)` (as seen above) is still required for Kani proofs placed under `tests/`. |
| 93 | +When this code is built by `cargo test`, the `kani` crate is not available, and so it would otherwise cause build failures. |
| 94 | +(Whereas the use of `dev-dependencies` under `tests/` does not need to be gated with `cfg(test)` since that code is already only built when testing.) |
0 commit comments