perlcov-perl - a replacement perl interpreter for use with PerlCov

NAME

perlcov-perl - a replacement perl interpreter for use with PerlCov

SYNOPSIS

perlcov-perl [perl-options] [script]

DESCRIPTION

The perlcov-perl program is a replacement perl interpreter that collects coverage and timing data about the script that it runs and updates the perlcov database. Each execution of perlcov-perl is denoted a run. One or more runs make up an experiment. Experiments in turn are grouped into projects.

The perlcov-perl program takes the same options as perl itself does (see perlrun for details).

The behaviour of perlcov-perl and the project and experiment names it will file the run under is controlled by a set of envionment variables ( see ENVIRONMENT for details).

Running under Test::Harness

It's good practice to structure your Perl code as CPAN style distributions even if you don't intend to distribute it on CPAN. CPAN style distributions put the test suite for the code in a directory called t and the perl module infrastructure then make sure these tests run when the make test command is issued. In this case it is the Test::Harness module that actually run the test scripts and summarize the results.

To collect coverage data for your test suite you need to make these tests run with perlcov-perl. This is done by setting the HARNESS_PERL environment variable to the value perlcov-perl before you run make test.

Example commands on Windows:

   set HARNESS_PERL=perlcov-perl
   nmake test

With many Unix shells you can do it with:

   HARNESS_PERL=perlcov-perl make test

ENVIRONMENT

PERLCOV_DB

The path and directory name of the coverage database. Run information is stored in this database. The directory will be created by perlcov-perl if it does not already exist.

The default depends on the kind of system you run. Normally, there is no need to override this.

PERLCOV_EXPERIMENT

The name to use for the experiemnt. This can be any string up to 40 characters long. Typically, this would be a timestamp, a version number, a revision control label or similar. If not specified it defaults to the current date and hostname.

Occurences of % followed by another character are templates that expand as follows:

%%

%

%T

Current date and time.

%t

Current time

%d

Current date

%p

The PID of the perlcov-perl process.

%P

The PID of the parent of the perlcov-perl process.

%H

The current hostname.

%h

The current hostname (short form).

PERLCOV_PERL_CORE_COLLECT

Boolean. If set and TRUE, makes perlcov-perl collect data about any bundled or installed modules used by the script. If not TRUE, data is only collected about the script itself and any uninstalled modules it uses.

PERLCOV_PROJECT

The name to use for the project. This can be any string up to 20 characters long.

If not provided perlcov-perl will try to figure it out from name field of META.yml or the DISTNAME variable in Makefile. If a project name can't be determined, then perlcov-perl will fail without running the script.

SEE ALSO

perlcov(1), pdk(1), perl(1), perlrun(1)

Coverage Tool is part of the Perl Dev Kit. More is information available at http://www.ActiveState.com/PerlDevKit/Purchase.

VERSION

This manpage documents Coverage Tool version 8.0.0 (build 289623)

COPYRIGHT

Copyright (C) 1998-2009 ActiveState Software Inc. All rights reserved.

Copyright 2001-2006, Paul Johnson (pjcj@cpan.org)

The current version of perlcov-perl use an embedded version of the Devel-Cover core to collect data. Devel-Cover is written by Paul Johnson and is available from CPAN. ActiveState Software Inc., has chosen to use Devel-Cover under the terms of the Artistic License.