Notes For CPAN Authors

Making distributions CPAN Testers friendly

"How can I indicate that my distribution only works on certain versions of Perl?"

A minimum Perl version should be specified with a "use VERSION" statement at the top of the Makefile.PL and/or Build.PL. Be sure to use the older style of version numbers. E.g.

# In Makefile.PL or Build.PL
use 5.006;     # NOT 5.6.0

You can also specify a prerequisite of 'perl' in a Build.PL, but older versions of Module::Build don't check this early enough when running Build.PL so you can't rely on it to avoid fatal (and confusing) errors running Build.PL. You should still do this to ensure that your perl prerequisite is included in META.yml.

# In Build.PL as an argument to Module::Build->new()
requires => {
    'perl' => 5.008001,
}

MakeMaker does not have an equivalent -- adding perl to PREREQ_PM is not supported.

"How can I indicate that my distribution requires a version of Perl with threads?"

The current paradigm is to allow thread-based modules to be installed on non-threaded Perls. As such, you should NOT put any such checks in your Makefile.PL, but should allow the module to be installed regardless.

The rationale for this is to allow modules/packages/applications to be developed and run on non-threaded Perls. For instance, threads::shared is available, but essential does nothing if used on non-threaded Perls (or in non-threaded applications). Thread::Queue similarly provides object-oriented FIFO queues on both threaded and non-threaded Perls.

In your test suite, adding the following preamble to the top of any test files that 'use threads;' will keep them from generating failures:

BEGIN {
  use Config;
  if (! $Config{'useithreads'}) {
      print("1..0 # Skip: Perl not compiled with 'useithreads'\n");
      exit(0);
  }
}

Additionally, if possible, you should try to include tests that test your module's functionality in non-threaded applications (i.e., when 'use threads;' is not used).

You also don't need to put in special checks for the 'threads' module in your module's code. Just using 'use threads;' will cause the following error message to occur:

This Perl not built to support threads

"How can I indicate that my distribution only works on a particular operating system?"

While it isn't a very elegant solution, the recommend approach is to either die in the Makefile.PL or Build.PL (or BAIL_OUT in a test file) with one of the following messages:

• No support for OS
• OS unsupported

CPAN Testers tools will look for one of those phrases and will send an NA (Not Available) report for that platform.

Devel-AssertOS is an experimental tool that you can bundle with your distribution in an inc/ directory and use in your Makefile.PL or Build.PL to die with the appropriate message if not on a supported OS:

# in a Makefile.PL or Build.PL
use lib 'inc';
use Devel::AssertOS qw(Linux FreeBSD Cygwin);

"How can I stop getting FAIL reports for missing libraries or other non-Perl dependencies?"

If you have some special dependencies and don't want to get CPAN Testers reports if a dependency is not available, just exit from the Makefile.PL or Build.PL normally (with an exit code of 0) before the Makefile or Build file is created.

exit 0 unless some_dependency_is_met();

Devel-CheckLib is an experimental tool that you can bundle with your distribution in an inc/ directory and use in your Makefile.PL or Build.PL to issue a warning and exit if a library is not available:

# in a Makefile.PL or Build.PL
use lib 'inc';
use Devel::CheckLib;  
check_lib_or_exit( lib => 'jpeg' );

See the documentation for instructions on specifying multiple libraries or specifying additional library paths to search.

Never, ever, set the MakeMaker parameter PREREQ_FATAL to true, it is a flawed invention. Not only has it the effect that no Makefile is being written thus preventing installers to actually try to install prerequisites. It also exits with an error code, so that cpantesters would rate it as a FAIL.

(vkon: I think this is not fair. Tester is not even getting Makefile and already sends FAIL. This feature is largely un-useful, and this is a bug in tester's smoking scenario, IMO.)

"How should I invoke perl from my test scripts?"

Use $^X or the Probe-Perl module. Perl might not be in the path, or your user might have several different version of perl installed, so using this variable will ensure the test is run with the appropriate perl binary.

If you need to test the use of $^X, rename your copy of perl to myperl:

myperl Makefile.PL
make test

Probe::Perl is a more correct choice, as it gets things right under some edge-cases on VMS, unlike $^X. But it does add another dependency to your code.

"Why am I being told 'Can't locate Devel/Autoflush.pm in @INC'?"

CPAN::Reporter sets PERL5OPT="-MDevel::Autoflush" to ensure Makefile.PL or Build.PL prompts are always visible. This error will show up when your tests or code execute 'perl' instead of $^X and the default perl in $ENV{PATH} does not have Devel::Autoflush installed. See the prior question on how to invoke perl safely.

"How can I get more detail about a failing test script?"

If the Test::Harness output in the CPAN Testers report is insufficient, you could email the tester and ask for a more detailed output to help diagnose your test failure. (See answers to "How do I contact a tester?" below.)

About CPAN Testers reports

"Why am I getting these reports?"

The short answer is that you uploaded a distribution, via PAUSE, to the CPAN.

The longer answer is that the CPAN Testers will test your distribution on their system, once PAUSE announces it has been indexed. They will run your test suite and submit reports on the outcome. If you have received one of these reports, it is likely that the test suite doesn't exist or cannot be found (UNKNOWN) or one or more of the tests in the test suite failed (FAIL).

"Can't CPAN Testers read? I have detailed the format I require for bug reports!"

Please do not get irate with CPAN Testers. They are there to try and help you. The reports they send are often automated, without any human intervention, and are simply the output of your own test suite. If you want the testers to produce something special, it is suggested you include test scripts that include all the necessary diagonostic information you will need to understand why your distribution failed.

If you ask nicely, I'm sure the tester who tested your distribution will try and help you solve the problem. Rejecting reports simply because they don't meet your expectations of what a bug report should look like does you no favours. Users often read the CPAN Testers website to see whether a distribution fails on a particular platform or perl combination. Ignoring that will only mean your distribution gets less usage than it might otherwise gain.

"Why are you testing (and failing) my Tk-ish module without an X server?"

Until very recently, Tk wouldn't build without a display. As a result, the testing software would look at the test failures for your module and think "ah well, one of his pre-requisites failed to build, so it's not his fault" and throw the report away. The most recent versions of Tk, however, *will* build without a display - it just skips all the tests. So the testing software sees that it passed, and thinks there must be something wrong with your module. You should check for a working Tk (and hence X11) environment by checking if MainWindow->new() throws an exception:

  my $mw = eval { MainWindow->new };
  if (!$mw) { ... skip tests ... }

"Why am I getting a FAIL/UNKNOWN/NA report when prerequisites are not met?"

Some early versions of CPAN Testers tools had bugs that did not properly catch when prerequisites were specified but not met. Please just ignore these reports.

"How can I stop getting these reports?"

At the moment, the suggestion is to use a filtering mechanism in your mail client of choice. However, this may mean you miss valid reports from users, so you might want to filter reports into a dedicated mail folder and periodically check it, deleting anything you are not interested in. At the moment there is no way for you to tell testers that you don't wish to receive reports, although a mechanism is currently being considered, that would allow the author to include an appropriate entry in the META.yml file, which the testing mechanism could then respect.

"How can I get more of these reports?"

Marcel Grünauer has written a script to fetch arbitrary reports: App::sync_cpantesters

"Can I tell if my module is being tested by an automated client (a.k.a. 'smoker')?"

Automated smoke testers should set $ENV{AUTOMATED_TESTING} to a true value. This allows authors to skip certain tests (or include certain tests) when the results are not being monitored by a human being.

One could even go so far as to halt building and testing a distribution under automated testing by exiting with zero at the top of the Makefile.PL or Build.PL file:

exit 0 if $ENV{AUTOMATED_TESTING};

"How do I contact a tester?"

Most testers will Cc you on FAIL and UNKNOWN test results, so you can just reply to the email. But if you're looking at test results through, eg, a web page, then this tool will convert a test report number into the tester's email address.