.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "uncov-gcov" "1" "January 20, 2024" "uncov v0.5" ""
.SH NAME
uncov\-gcov is coverage information collector for C and C++ languages
that can be used with \f[B]uncov(1)\f[R].
.PP
\f[B]NOTE:\f[R] since uncov\-gcov isn\[cq]t the only way to collect C
and C++ coverage for uncov anymore, its use is discouraged.
It is provided in case it might work better in some contexts because of
some unique options (like taking exclusion markers of LCOV into
account).
It might be a good idea to switch to using \[lq]uncov new\-gcovi\[rq]
subcommand.
.SH SYNOPSIS
\f[B]uncov\-gcov\f[R] \f[B]\-h|\-\-help\f[R]
.PP
\f[B]uncov\-gcov\f[R] \f[B]\-v|\-\-version\f[R]
.PP
\f[B]uncov\-gcov\f[R] \f[B][<options>\&...]\f[R]
.SH OPTIONS
.SS \f[B]\-\-help, \-h\f[R]
Displays short usage help.
.SS \f[B]\-\-version, \-v\f[R]
Displays version information.
.SS \f[B]\-\-verbose\f[R]
Print verbose messages.
.SS \f[B]\-\-dryrun\f[R]
Run the script without printing report.
.SS \f[B]\-\-gcov\f[R] [=gcov]
Set the location of gcov.
.SS \f[B]\-\-gcov\-options\f[R] [=\[lq]\[rq]]
Set the options given to gcov.
.SS \f[B]\-r\f[R], \f[B]\-\-root\f[R] [=.]
Set the root directory.
.SS \f[B]\-b\f[R], \f[B]\-\-build\-root\f[R] [={discovered}]
Set the directory from which gcov will be called; by default gcov is run
in the directory of the .o files; however the paths of the sources are
often relative to the directory from which the compiler was run and
these relative paths are saved in the .o file; when this happens, gcov
needs to run in the same directory as the compiler in order to find the
source files.
.SS \f[B]\-\-collect\-root\f[R] [={value of \-\-root}]
Directory to look gcov files in.
.SS \f[B]\-e\f[R], \f[B]\-\-exclude\f[R] [=\[lq]\[rq]]
List of paths to exclude.
Can be specifieid multiple times.
.PP
Examples:
.IP
.EX
uncov\-gcov \-\[rs]\-exclude build\-release \-\[rs]\-exclude build\-debug ...
uncov\-gcov \-\[rs]\-exclude build\-release build\-debug ...
uncov\-gcov \-\[rs]\-exclude build* ...
.EE
.SS \f[B]\-i\f[R], \f[B]\-\-include\f[R] [=\[lq]\[rq]]
List of paths to include.
Can be specifieid multiple times.
See \f[B]\-\-exclude\f[R] for examples.
.SS \f[B]\-E\f[R], \f[B]\-\-exclude\-pattern\f[R] [=\[lq]\[rq]]
Set exclude file/directory pattern.
.SS \f[B]\-x\f[R], \f[B]\-\-extension\f[R] [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
Set extension of files to process.
.SS \f[B]\-n\f[R], \f[B]\-\-no\-gcov\f[R]
Do not run gcov.
.SS \f[B]\-\-encodings\f[R] [=utf\-8,latin\-1]
Source encodings to try in order of preference.
.SS \f[B]\-\-dump\f[R] <file>
Dump JSON payload to a file.
.SS \f[B]\-\-follow\-symlinks\f[R]
Follow symlinks.
.SS \f[B]\-c\f[R], \f[B]\-\-capture\-worktree\f[R]
Make a dangling commit if working directory is dirty.
.SS \f[B]\-\-ref\-name\f[R] [={discovered}]
Force custom ref name.
.SS \f[B]\-\-cpp\-dtor\-invocations\f[R]
Count coverage for C++ destructor invocations, which tends to show up at
lines that have the closing brace (\f[CR]{\f[R]).
.SH USAGE
uncov\-gcov can be used to generate coverage, but it seems to not play
well with out\-of\-tree builds (some coverage is missing, this issue is
inherited from its origin), so the recommended way of recording coverage
information is as follows:
.IP
.EX
# reset coverage counters from previous runs
find . \-name \[aq]*.gcda\[aq] \-delete

# run tests here with something like \[ga]make check\[ga]

# generage coverage for every object file found (change \[dq].\[dq] to build root)
find . \-name \[aq]*.o\[aq] \-exec gcov \-p {} +

# generage and combine coverage reports (\-\[rs]\-capture\-worktree automatically
# makes stray commit if repository is dirty)
uncov\-gcov \-\[rs]\-root . \-\[rs]\-no\-gcov \-\[rs]\-capture\-worktree \-\[rs]\-exclude tests | uncov new

# remove coverage reports
find . \-name \[aq]*.gcov\[aq] \-delete
.EE
.PP
These commands can be put in a separate script or embedded directly into
build system.
.SH SEE ALSO
\f[B]uncov\f[R](1), \f[B]uncov\-web\f[R](1)
.SH AUTHORS
xaizek <xaizek@posteo.net>.