[Haskell-cafe] Configuring cabal to tell HPC to ignore certain functions

[Ryan Scott]

Hi Ivan,

Short answer: I'm not aware of a way to automate the process of
excluding certain definitions from cabal-generated HPC coverage
reports.

Long answer: there is a way to manually modify HPC coverage reports
using the hpc overlay command. Sadly, most the existing documentation
on this command [1] is pretty sparse, so the only way I was able to
discover this was by reading the original HPC paper [2] (in that
paper, `hpc overlay` is called `hpc-makemtix`) and by finding an
example of how to use `hpc overlay` in GHC's test suite [3]. To
translate that example into prose: suppose you have the following
program (hpc001.hs):

    main = print (const "Hello" "World")

Here, the expression "World" is never evaluated, so by default HPC
will claim that there is no coverage for it. This is pretty silly,
however, so we'd like to instruct HPC not to warn about "World". To do
so, first compile the example above with coverage enabled and run it:

    $ ghc -fhpc hpc001.hs    $ ./hpc001

This should generate an hpc001.tix file. If you run `hpc markup
hpc001.tix` and look at the resulting HTML report, you'll see that it
warns about "World". Let's fix that. To do so, we have to define an
HPC overlay file. The example given in GHC's test suite
(sample_overlay.ovr) is:

    module "Main" {
      inside "main" {
        tick "\"World\"" on line 1;
      }
    }

While I can't find a reference for the syntax that HPC overlay files
use, this particular example is pretty self-explanatory: don't report
about the expression "World" on line 1, which is found inside the
`main` function in the `Main` module. In order to make use of this
overlay file, we first have to convert it to a .tix file:

    $ hpc overlay sample_overlay.ovr > sample_overlay1.tix

Then we have to combine it with our original .tix file:

    $ hpc combine hpc_sample.tix sample_overlay1.tix > total1.tix

If we run `hpc markup total1.txt`, we now see that HPC no longer warns
about "World", just as we'd hoped for.

That is where my understanding of this feature ends, however. In
particular, I'm not aware of a better way to generate overlay files
(other than to write them by hand, which still feels somewhat
laborious), and I'm not aware of any deeper integration with cabal so
that these overlay files would be picked up and automatically applied
(e.g., for reporting coverage on Hackage). Given that the HPC
documentation for `hpc overlay` [1] labels this as an experimental
feature, I'd be surprised if such tooling or integration existed. I
agree that it would be cool if did, however.

Best,

Ryan
-----
[1] https://hpc-bin.readthedocs.io/en/latest/hpc.html#hpc-overlay-and-hpc-draft
[2] https://dl.acm.org/doi/abs/10.1145/1291201.1291203
[3] https://gitlab.haskell.org/ghc/ghc/-/blob/e39c8c993c1da534c5893ca418d1fa4cbb9e0a0a/testsuite/tests/hpc/simple/tixs/test.T#L44-50
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20241024/5d6a6fc2/attachment.html>