Обсуждение: Add documentation for coverage reports with meson

Hi all,

I have mentioned on a different thread of -docs that we have no
documentation to achieve $subject, so attached is a patch to add
something.  This can be done with the following steps:
meson setup -Db_coverage=true .. blah
ninja
meson test
ninja coverage-html

As far as I can see, there is no option to generate anything else than
a HTML report?  This portion is telling the contrary, still it does
not seem to work here and ninja does the job with coverage-html or
coverage as only available targets:
https://mesonbuild.com/howtox.html#producing-a-coverage-report

Side issue: the current code generates no reports for the files that
are automatically generated in src/backend/nodes/, which are actually
part of src/include/ for a meson build.  I have not looked into that
yet.

Thoughts?
--
Michael

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