view release on metacpan or  search on metacpan

lib/Devel/Cover.pm  view on Meta::CPAN

replacing perl's runops function.  It is still possible to switch to that mode
of operation, but this now gets little testing and will probably be removed
soon.  You probably don't care about any of this.

The most appropriate mailing list on which to discuss this module would be
perl-qa.  See L<https://lists.perl.org/list/perl-qa.html>.

The Devel::Cover repository can be found at
L<https://github.com/pjcj/Devel--Cover>.  This is also where problems should be
reported.

=head1 REQUIREMENTS AND RECOMMENDED MODULES

=head2 REQUIREMENTS

=over

=item * Perl 5.20.0 or greater.

The latest version of Devel::Cover on which Perl 5.12 to 5.18 was supported was
1.51.  The latest version of Devel::Cover on which Perl 5.10 was supported was
1.38.  The latest version of Devel::Cover on which Perl 5.8 was supported was
1.23.  Perl versions 5.6.1 and 5.6.2 were not supported after version 1.22.
Perl versions 5.6.0 and earlier were never supported.  Using Devel::Cover with
Perl 5.8.7 was always problematic and frequently lead to crashes.

Different versions of perl may give slightly different results due to changes
in the op tree.

=item * The ability to compile XS extensions.

This means a working C compiler and make program at least.  If you built perl
from source you will have these already and they will be used automatically.
If your perl was built in some other way, for example you may have installed
it using your Operating System's packaging mechanism, you will need to ensure
that the appropriate tools are installed.

=item * L<Storable> and L<Digest::MD5>

Both are in the core in Perl 5.8.0 and above.

=back

=head2 OPTIONAL MODULES

=over

=item * L<Template>, and either L<PPI::HTML> or L<Perl::Tidy>

Needed if you want syntax highlighted HTML reports.

=item * L<Pod::Coverage> (0.06 or above) or L<Pod::Coverage::CountParents>

One is needed if you want Pod coverage.  If L<Pod::Coverage::CountParents> is
installed, it is preferred.

=item * L<Test::More>

Required if you want to run Devel::Cover's own tests.

=item * L<Test::Differences>

Needed if the tests fail and you would like nice output telling you why.

=item * L<Template> and L<Parallel::Iterator>

Needed if you want to run cpancover.

=item * L<JSON::MaybeXS>

JSON is used to store the coverage database if it is available. JSON::MaybeXS
will select the best JSON backend installed.

=back

=head2 Use with mod_perl

By adding C<use Devel::Cover;> to your mod_perl startup script, you should be
able to collect coverage information when running under mod_perl.  You can
also add any options you need at this point.  I would suggest adding this as
early as possible in your startup script in order to collect as much coverage
information as possible.

Alternatively, add -MDevel::Cover to the parameters for mod_perl.
In this example, Devel::Cover will be operating in silent mode.

  PerlSwitches -MDevel::Cover=-silent,1

=head1 OPTIONS

  -blib               - "use blib" and ignore files matching \bt/ (default true
                        if blib directory exists, false otherwise)
  -coverage criterion - Turn on coverage for the specified criterion.  Criteria
                        include statement, branch, condition, path, subroutine,
                        pod, time, all and none (default all available)
  -db cover_db        - Store results in coverage db (default ./cover_db)
  -dir path           - Directory in which coverage will be collected (default
                        cwd)
  -ignore RE          - Set regular expressions for files to ignore (default
                        "/Devel/Cover\b")
  +ignore RE          - Append to regular expressions of files to ignore
  -inc path           - Set prefixes of files to include (default @INC)
  +inc path           - Append to prefixes of files to include
  -loose_perms val    - Use loose permissions on all files and directories in
                        the coverage db so that code changing EUID can still
                        write coverage information (default off)
  -merge val          - Merge databases, for multiple test benches (default on)
  -select RE          - Set regular expressions of files to select (default
                        none)
  +select RE          - Append to regular expressions of files to select
  -silent val         - Don't print informational messages (default off)
  -subs_only val      - Only cover code in subroutine bodies (default off)
  -replace_ops val    - Use op replacing rather than runops (default on)
  -summary val        - Print summary information if val is true (default on)

=head2 More on Coverage Options

You can specify options to some coverage criteria.  At the moment only pod
coverage takes any options.  These are the parameters which are passed into
the L<Pod::Coverage> constructor.  The extra options are separated by dashes,
and you may specify as many as you wish.  For example, to specify that all