Add documentation for coverage reports with meson

On 28.02.23 09:49, Michael Paquier wrote:

-    when compiling with GCC, and it requires the <command>gcov</command>
-    and <command>lcov</command> programs.
+    when compiling with GCC, and it requires the <command>gcov</command>,
+    <command>lcov</command> and <command>genhtml</command> programs.

genhtml is part of the lcov package. I think it would be confusing to
mention it explicitly, since you won't be able to find it as something
to install. Maybe leave the original list and change "programs" to
"packages"?

-   <para>
-    A typical workflow looks like this:
+   <sect2 id="regress-coverage-configure">
+    <title>Coverage with <filename>configure</filename></title>
+    <para>
+     A typical workflow looks like this:

In the installation chapter we use titles like "Building and
Installation with Autoconf and Make" and "Building and Installation with
Meson". We should use analogous wordings here.

+    <para>
+     A typical workflow looks like this:
+<screen>
+meson setup -Db_coverage=true ... OTHER OPTIONS ...
+ninja
+meson test
+ninja coverage-html
+</screen>
+     Then point your HTML browser
+     to <filename>./meson-logs/coveragereport/index.html</filename>.
+    </para>

This ignores which directory you have to be in. The meson calls have to
be at the top level, the ninja calls have to be in the build directory.
We should be more precise here, otherwise someone trying this will find
that it doesn't work.

Personally I use "meson compile" instead of "ninja"; I'm not sure what
the best recommendation is, but that least that way all the initial
commands are "meson something" instead of going back and forth.

On Fri, Mar 03, 2023 at 10:10:15AM +0100, Peter Eisentraut wrote:

genhtml is part of the lcov package. I think it would be confusing to
mention it explicitly, since you won't be able to find it as something to
install. Maybe leave the original list and change "programs" to "packages"?

Makes sense.

In the installation chapter we use titles like "Building and Installation
with Autoconf and Make" and "Building and Installation with Meson". We
should use analogous wordings here.

OK, changed to something like that.

This ignores which directory you have to be in. The meson calls have to be
at the top level, the ninja calls have to be in the build directory. We
should be more precise here, otherwise someone trying this will find that it
doesn't work.

Hmm. I can see that it is possible to pass the repository to move to
with -C, still it is simpler to move into the build repository.

Personally I use "meson compile" instead of "ninja"; I'm not sure what the
best recommendation is, but that least that way all the initial commands are
"meson something" instead of going back and forth.

Using meson compile is fine by me for the docs. Note that I cannot
see an option with meson to do coverage reports, and my environment
uses 1.0.1. Only ninja handles that.

Updated version attached.
--
Michael

On 03.03.23 12:12, Michael Paquier wrote:

+<screen>
+meson setup -Db_coverage=true ... OTHER OPTIONS ... builddir/
+cd builddir/
+meson compile
+meson test
+ninja coverage-html
+</screen>

The "cd" command needs to be moved after the meson commands, and the
meson commands need to have a -C builddir option. So it should be like

<screen>
meson setup -Db_coverage=true ... OTHER OPTIONS ... builddir/
meson compile -C builddir
meson test -C builddir
cd builddir/
ninja coverage-html
</screen>

Otherwise, this looks good to me.

On Wed, Mar 08, 2023 at 05:23:48PM +0100, Peter Eisentraut wrote:

The "cd" command needs to be moved after the meson commands, and the meson
commands need to have a -C builddir option.

Still that's not mandatory, is it? The compile and test commands of
meson work as well if you are located at the root of the build
directory, AFAIK.

So it should be like

<screen>
meson setup -Db_coverage=true ... OTHER OPTIONS ... builddir/
meson compile -C builddir
meson test -C builddir
cd builddir/
ninja coverage-html
</screen>

Otherwise, this looks good to me.

Anyway, this works as well and I don't have any arguments against
that. So I have used your flow, and applied the patch. I have
actually switched my own scripts to rely more on -C, removing direct
calls to ninja ;p

Thanks for the feedback.
--
Michael