diff --git a/README.md b/README.md index 3d60da39..1e1ad9a4 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,8 @@ details of how it is generated are in the [worked example](#Example). Refer to [**aantron/bisect-starter-dune**][dune-repo], which produces [this report][dune-report]. -1. [Depend on Bisect_ppx in your `opam` file](https://github.com/aantron/bisect-starter-dune/blob/master/bisect-starter-dune.opam#L10): +1. [Depend on Bisect_ppx](https://github.com/aantron/bisect-starter-dune/blob/master/bisect-starter-dune.opam#L10) + in your `opam` file: ``` depends: [ @@ -60,29 +61,57 @@ Refer to [**aantron/bisect-starter-dune**][dune-repo], which produces ``` 2. [Mark the code under test for preprocessing by - `bisect_ppx`](https://github.com/aantron/bisect-starter-dune/blob/master/dune#L4) - (but don't preprocess the tester itself): + `bisect_ppx`](https://github.com/aantron/bisect-starter-dune/blob/master/dune#L4) in your `dune` file: + + ```ocaml + (* -*- tuareg -*- *) + + let preprocess = + match Sys.getenv "BISECT_ENABLE" with + | "yes" -> "(preprocess (pps bisect_ppx))" + | _ | exception _ -> "" + + let () = Jbuild_plugin.V1.send @@ {| - ```scheme (library (public_name my_lib) - (preprocess (pps bisect_ppx --conditional))) + |} ^ preprocess ^ {|) + + |} ``` + This uses Dune's + [OCaml syntax](https://dune.readthedocs.io/en/stable/advanced-topics.html#ocaml-syntax) + to completely take `bisect_ppx` out as a dependency, except when the + environment variable `BISECT_ENABLE` is set to `yes`. This is so that you + can release your project without it depending on `bisect_ppx` for non-`dev` + builds. + + After [ocaml/dune#57][dune-57], Dune will have a lighter-weight built-in + syntax for conditional preprocessing. + + For now, the OCaml syntax can be understood as prepending a few lines of + OCaml code to a regular `dune` file, and then replacing the `preprocess` + stanza with `|} ^ preprocess ^ {|`. See + [here](https://github.com/aantron/bisect-starter-dune/commit/24ffb2153d3c42ff166c78a9f55095bd12f10f4e#diff-cabdb1014252d39ac018f447e7d5fbc2) + for a neat summary of the patch. + 3. Build and run your test binary. In addition to testing your code, when exiting, it will write one or more files with names like - `bisect0123456789.coverage`. + `bisect0123456789.coverage`: ``` BISECT_ENABLE=yes dune runtest --force ``` - `BISECT_ENABLE=yes` turns on instrumentation. If you run `dune runtest` (or - any other build) without it, Bisect_ppx will pass the code through - unchanged (i.e., without adding instrumentation). + The `--force` flag forces all your tests to run, which is needed for an + accurate coverage report. + + To run tests without coverage, do - At the moment, if you switch between building with and without - instrumentation, you have to run `dune clean` in between the builds. + ``` + dune runtest + ``` 4. Generate the [coverage report][dune-report] in `_coverage/index.html`: @@ -90,22 +119,11 @@ Refer to [**aantron/bisect-starter-dune**][dune-repo], which produces bisect-ppx-report html ``` -4. For releasing, you have two options: + You can also generate a short summary in the terminal: - - If you don't want a dependency on package `bisect_ppx`, you have to - manually remove `(preprocess (pps bisect_ppx))` from your `dune` files. - - If a dependency on Bisect_ppx is okay, you don't have to do anything. A - regular build command, without `BISECT_ENABLE=yes` will produce - uninstrumented code: - - ``` - ["dune" "build" "-p" name "-j" $jobs] - ``` - - This choice is due to a limitation of Dune that we hope to address in - [ocaml/dune#57][dune-57]. After that, `BISECT_ENABLE=yes` won't be - necessary anymore, and you will be able to release without a dependency on - Bisect_ppx, without having to edit any files. + ``` + bisect-ppx-report summary + ``` [dune-repo]: https://github.com/aantron/bisect-starter-dune#readme [dune-report]: https://aantron.github.io/bisect-starter-dune/