/ 
CPAN-Reporter-1.2020
River stage two • 11 direct dependents • 16 total dependents
/ CPAN::Reporter::API

NAME

CPAN::Reporter::API - Programmer's interface to CPAN::Reporter

VERSION

version 1.2020

FUNCTIONS

CPAN::Reporter provides only a few public function for use within CPAN.pm. They are not imported during use. Ordinary users will never need them.

configure()

CPAN::Reporter::configure();

Prompts the user to edit configuration settings stored in the CPAN::Reporter config.ini file. It will create the configuration file if it does not exist. It is automatically called by CPAN.pm when initializing the 'test_report' option, e.g.:

cpan> o conf init test_report

record_command()

($output, $exit_value) = CPAN::Reporter::record_command( $cmd, $secs );

Takes a command to be executed via system(), but wraps and tees it to show the output to the console, capture the output, and capture the exit code. Returns an array reference of output lines (merged STDOUT and STDERR) and the return value from system(). Note that this is $?, so the actual exit value of the command will need to be extracted as described in perlvar.

If the command matches /\b(?:Makefile|Build)\.PL\b/, then Devel::Autoflush is added to PERL5OPT to force autoflushing of user prompts.

If the command includes a pipe character ('|'), only the part of the command prior to the pipe will be wrapped and teed. The pipe will be applied to the execution of the wrapper script. This is essential to capture the exit value of the command and should be otherwise transparent.

If a non-zero $secs argument is provided, the command will be run with a timeout of $secs (seconds) if the appropriate process management modules are available. On Win32, Win32::Job must be available; on Unix, Proc::Killfam must be available. Otherwise, code will fall-back to running without a timeout.

Also, on Win32, the first space-separated element of the command must be absolute, or else ".exe" will be appended and the PATH searched for a matching command.

If the attempt to record fails, a warning will be issued and one or more of $output or $exit_value will be undefined.

grade_make()

CPAN::Reporter::grade_make( $dist, $command, \@output, $exit);

Given a CPAN::Distribution object, the system command used to build the distribution (e.g. "make", "perl Build"), an array of lines of output from the command and the exit value from the command, grade_make() determines a grade for this stage of distribution installation. If the grade is "pass", grade_make() does not send a CPAN Testers report for this stage and returns true to signal that the build was successful. Otherwise, a CPAN Testers report is sent and grade_make() returns false.

grade_PL()

CPAN::Reporter::grade_PL( $dist, $command, \@output, $exit);

Given a CPAN::Distribution object, the system command used to run Makefile.PL or Build.PL (e.g. "perl Makefile.PL"), an array of lines of output from the command and the exit value from the command, grade_PL() determines a grade for this stage of distribution installation. If the grade is "pass", grade_PL() does not send a CPAN Testers report for this stage and returns true to signal that the Makefile.PL or Build.PL ran successfully. Otherwise, a CPAN Testers report is sent and grade_PL() returns false.

grade_test()

CPAN::Reporter::grade_test( $dist, $command, \@output, $exit);

Given a CPAN::Distribution object, the system command used to run tests (e.g. "make test"), an array of lines of output from testing and the exit value from the system command, grade_test() determines a grade for distribution tests. A CPAN Testers report is then sent unless specified prerequisites were not satisfied, in which case the report is discarded. This function returns true if the grade is "pass" or "unknown" and returns false, otherwise.

test() -- DEPRECATED

CPAN::Reporter::test( $cpan_dist, $system_command );

This function is maintained for backwards compatibility. It effectively wraps the functionality of record_command() and grade_test() into a single function call. It takes a CPAN::Distribution object and the system command to run distribution tests.

SEE ALSO

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004