Skip to content

Commit 85a59bc

Browse files
QinyuanWujaisnanfeliperodri
authored
Add documentation to run Kani on single harnesses (#85)
This PR adds to the documentation in the Verification Tools->Kani section of the [challenge book](https://model-checking.github.io/verify-rust-std/tools/kani.html). ### Changes - New step to help Kani user run specific proofs and identify harness full names. ### Issue I tried to follow step 1 & 2 but Kani could not find the harnesses in the example code. At this point there are many proofs in the library so I couldn't find the full name of the harness in the example code by just running all proofs. I tried to move `example.rs` into `library/core/src/ptr/` and use `--harness ptr::verify::example` or `--harness dummy_proof` but both got `error: no harnesses matched the harness filter`. --------- Co-authored-by: Jaisurya Nanduri <[email protected]> Co-authored-by: Felipe R. Monteiro <[email protected]>
1 parent 024e117 commit 85a59bc

File tree

1 file changed

+11
-1
lines changed

1 file changed

+11
-1
lines changed

doc/src/tools/kani.md

+11-1
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ Here is a short tutorial of how to use Kani to verify proofs for the standard li
5858
Create a local copy of the [model-checking fork](https://github.com/model-checking/verify-rust-std) of the Rust Standard Library. The fork comes with Kani configured, so all you'll need to do is to call Kani's building-block APIs (such as
5959
`assert`, `assume`, `proof` and [function-contracts](https://github.com/model-checking/kani/blob/main/rfc/src/rfcs/0009-function-contracts.md) such as `modifies`, `requires` and `ensures`) directly.
6060

61+
6162
For example, insert this module into an existing file in the core library, like `library/core/src/hint.rs` or `library/core/src/error.rs` in your copy of the library. This is just for the purpose of getting started, so you can insert in any existing file in the core library if you have other preferences.
6263

6364
``` rust
@@ -97,7 +98,7 @@ The command `kani verify-std` is a sub-command of the `kani`. This specific sub-
9798
- `"path/to/library"`: This argument specifies the path to the modified Rust Standard Library that was prepared earlier in the script. For example, `./library` or `/home/ubuntu/verify-rust-std/library`
9899
- `--target-dir "path/to/target"`: This optional argument sets the target directory where Kani will store its output and intermediate files. For example, `/tmp` or `/tmp/verify-std`
99100

100-
Apart from these, you can use your regular `kani-args` such as `-Z function-contracts` and `-Z stubbing` depending on your verification needs.
101+
Apart from these, you can use your regular `kani-args` such as `-Z function-contracts`, `-Z stubbing` and `-Z mem-predicates` depending on your verification needs. If you run into a Kani error that says `Use of unstable feature`, add the corresponding feature with `-Z` to the command line.
101102
For more details on Kani's features, refer to [the features section in the Kani Book](https://model-checking.github.io/kani/reference/attributes.html)
102103

103104
### Step 3 - Check verification result
@@ -143,6 +144,15 @@ Verification Time: 0.01885804s
143144
Complete - 1 successfully verified harnesses, 0 failures, 1 total.
144145
```
145146

147+
Now you can write proof harnesses to verify specific functions in the library.
148+
The current convention is to keep proofs in the same module file of the verification target.
149+
To run Kani for an individual proof, use `--harness [harness_function_name]`.
150+
Note that Kani will batch run all proofs in the library folder if you do not supply the `--harness` flag.
151+
If Kani returns the error `no harnesses matched the harness filter`, you can give the full name of the harness.
152+
For example, to run the proof harness named `check_new` in `library/core/src/ptr/unique.rs`, use
153+
`--harness ptr::unique::verify::check_new`. To run all proofs in `unique.rs`, use `--harness ptr::unique::verify`.
154+
To find the full name of a harness, check the Kani output and find the line starting with `Checking harness [harness full name]`.
155+
146156
## More details
147157

148158
You can find more information about how to install and how you can customize your use of Kani in the

0 commit comments

Comments
 (0)