NAME
Devel::XSCover::Build - the instrumented build of a distribution
SYNOPSIS
use Devel::XSCover::Build;
my $build = Devel::XSCover::Build->new(dir => '.');
my $status = $build->run;DESCRIPTION
Rebuilds every XS and C source of a distribution with the compiler's coverage instrumentation. The flags go on the make command line as OPTIMIZE and OTHERLDFLAGS, so the distribution's own Makefile.PL is never edited and its CCFLAGS stay as they are. The sources are touched first so make rebuilds every object. make clean is never run.
METHODS
new
my $build = Devel::XSCover::Build->new(%options);Options: dir (the distribution directory), make, perl, cc (the compiler, from perl's configuration by default), gcov (a tool overriding the detection), flow (the flow graph's kind overriding the detection), conditions (condition coverage on or off, decided by the compiler when not given), dry, silent and skip (directory names not touched, blib, cover_db and .git by default).
conditions
True when the build asks the compiler for condition coverage: gcc 14 and later have -fcondition-coverage, which records for every term of a decision whether its true and its false outcome each decided the result, and gcov --conditions reports it. Other compilers have nothing of the kind in gcov's output, so the condition column stays empty for C with them.
flow_kind
How the gcov tool can give the flow graph beside its text: llvm when it is LLVM's, which has --dump, gcc when it is gcc 9 or later, which has --json-format, and empty for an older gcov, whose branches then come from the blocks in its text alone. The flow option overrides the detection.
compiler
my $c = $build->compiler;Runs the compiler with --version and returns a hash reference with name (clang, gcc or unknown), major and banner.
gcov_command
my @cmd = @{ $build->gcov_command };The gcov tool as a list of words. For clang it is the gcov on the path when that is LLVM's (as on macOS), else llvm-cov gcov, else on macOS the one xcrun finds. For gcc it is gcov-N for the compiler's major version when on the path, else gcov. The gcov option overrides all of that.
flags
my @flags = $build->flags;The make macros: OPTIMIZE with -O0 -g, the coverage flags, atomic profile updates (threads lose half their counts without them) and -fcondition-coverage when conditions says so, and OTHERLDFLAGS with the coverage flags.
needs_configure
True when there is no Makefile or it is older than Makefile.PL.
clean_globs
The globs of the clean entry in Makefile.PL, with $(DISTNAME) filled in and any other macro dropped.
tarballs_at_risk
The archives in the directory that those globs match. A stale Makefile reruns clean by itself when Makefile.PL is run, and that takes them.
configure
Runs perl Makefile.PL when needed, warning first when tarballs are at risk. Returns the exit status.
touch
Sets the modification time of every .xs, .c, .cc, .cpp, .cxx, .h, .hh and .hpp under the directory to now, skipping the directories in skip, and leaving alone a .c beside a .xs of the same name, which xsubpp writes: touched with its source, it would be as new as it and never written again, and the build would compile the C of the last run. Returns the files touched.
build
Runs make with the flags. Returns the exit status.
run
configure, touch and build in that order, stopping at the first failure. Returns the exit status.
dir
The distribution directory.