This plugin gives you a new tag, coverage
, which you can use to mark your
source files for coverage analysis by Bisect_ppx. The plugin is in the public
domain, so you can freely link with it, customize and incorporate
it, and/or include it in releases.
It is used like this:
-
Install the plugin:
opam install bisect_ppx-ocamlbuild
-
Create a
myocamlbuild.ml
file in your project root, with the following contents:open Ocamlbuild_plugin let () = dispatch Bisect_ppx_plugin.dispatch
If you already have
myocamlbuild.ml
, you just need to callBisect_ppx_plugin.handle_coverage ()
somewhere in it. -
Add
-use-ocamlfind -plugin-tag 'package(bisect_ppx-ocamlbuild)'
to your Ocamlbuild invocation. -
Now, you have a new tag available, called
coverage
. Make your_tags
file look something like this:<src/*>: coverage # For instrumentation <tests/test.{byte,native}>: coverage # For linking
-
Now, if you build while the environment variable
BISECT_COVERAGE
is set toYES
, the files insrc
will be instrumented for coverage analysis. Otherwise, the tag does nothing, so you can build the files for release. So, to build, you will have two targets with commands like these:# For tests BISECT_COVERAGE=YES ocamlbuild -use-ocamlfind \ -plugin-tag 'package(bisect_ppx-ocamlbuild)' tests/test.native -- # For release ocamlbuild -use-ocamlfind \ -plugin-tag 'package(bisect_ppx-ocamlbuild)' src/my_project.native
If you don't want to make Bisect_ppx a hard build dependency just for the
coverage
tag, you can work the contents of Bisect_ppx_plugin
directly into your myocamlbuild.ml
. Use them to replace the call to
Bisect_ppx_plugin.dispatch
. In that case, you should omit the second step.
Since OASIS uses Ocamlbuild, the instructions are similar:
-
Install the plugin:
opam install bisect_ppx-ocamlbuild
-
At the top of your
_oasis
file are the package fields, such as the name and version. Add these:OCamlVersion: >= 4.01 AlphaFeatures: ocamlbuild_more_args XOCamlbuildPluginTags: package(bisect_ppx-ocamlbuild)
Then, run
oasis setup
. -
You should have a
myocamlbuild.ml
file in your project root. Near the bottom, after(* OASIS_STOP *)
, you will have a line like this one, if you have not yet modified it:Ocamlbuild_plugin.dispatch dispatch_default;;
replace it with
let () = dispatch (MyOCamlbuildBase.dispatch_combine [MyOCamlbuildBase.dispatch_default conf package_default; Bisect_ppx_plugin.dispatch])
-
This enables the
coverage
tag. Tag your source files as described in the Ocamlbuild instructions. Insert the tags after the line# OASIS STOP
. -
Use the
BISECT_COVERAGE
environment variable to enable coverage analysis:# For tests BISECT_COVERAGE=YES ocaml setup.ml -build && test.native # For release ocaml setup.ml -build
As in the Ocamlbuild instructions, if you don't want to make Bisect_ppx a build
dependency, you can work the contents of Bisect_ppx_plugin
directly into myocamlbuild.ml
. Use them to replace the call to
Bisect_ppx_plugin.dispatch
. In that case, you don't want to put the package
fields in the first step into your _oasis
file.