NAME

CPAN::cpanminus::reporter::RetainReports - Retain reports on disk rather than transmitting them

SYNOPSIS

    use CPAN::cpanminus::reporter::RetainReports;

    my $cpanmdir                        = '/home/username/.cpanm';
    my $log                             = "$cpanmdir/build.log";
    local $ENV{PERL_CPANM_HOME}         = $cpanmdir;
    local $ENV{PERL_CPAN_REPORTER_DIR}  = '/home/username/.cpanreporter';

    my $reporter = CPAN::cpanminus::reporter::RetainReports->new(
        force               => 1,           # ignore mtime check on cpanm build.log
        build_dir           => $cpanmdir,
        build_logfile       => $log,
        'ignore-versions' => 1,
    );

    my $analysisdir = '/home/username/bbc/testing/results/perl-5.27.0';
    $reporter->set_report_dir($analysisdir);
    $reporter->run;

DESCRIPTION

This library parses the output of a build.log generated by running cpanm and writes the output of that parsing to disk for later analysis or processing.

This is alpha code; the API is subject to change.

Rationale: Who Should Use This Library?

This library is a subclass of Breno G. de Oliveira's CPAN library App-cpanminus-reporter. That library provides the utility program cpanm-reporter|http://search.cpan.org/dist/App-cpanminus-reporter-0.17/bin/cpanm-reporter a way to generate and transmit CPANtesters reports after using Tatsuhiko Miyagawa's cpanm utility to install libraries from CPAN.

Like similar test reporting methodologies, App-cpanminus-reporter does not retain test reports on disk once they have been transmitted to CPANtesters. Whether a particular module passed or failed its tests is very quickly reported to http://fast-matrix.cpantesters.org/ and, after a lag, the complete report is posted to http://matrix.cpantesters.org/. That works fine under normal circumstances, but if there are any technical problems with those websites the person who ran the tests originally has no easy access to reports -- particularly to reports of failures. Quick access to reports of test failures is particularly valuable when testing a library against specific commits to the Perl 5 core distribution and against Perl's monthly development releases.

This library is intended to provide at least a partial solution to that problem. It is intended for use by at least three different kinds of users:

• People working on the Perl 5 core distribution or the Perl toolchain

  These individuals (commonly known as the Perl 5 Porters (P5P) and the Perl Toolchain Gang) often want to know the impact on the most commonly used CPAN libraries of (a) a particular commit to Perl 5's master development branch (known as blead) or some other branch in the repository; or (b) a monthly development release of perl (5.27.1, 5.27.2, etc.). After installing blead, a branch or a monthly dev release, they often want to install hundreds of modules at a time and inspect the results for breakage.

• CPAN library authors and maintainers

  A diligent CPAN maintainer pays attention to whether her libraries are building and testing properly against Perl 5 blead. Such a maintainer can use this library to get reports more quickly than waiting upon CPANtesters.

• People maintaining lists of CPAN libraries which they customarily install with perl

  Organizations which use many CPAN libraries in their production tend to keep a curated list of them, often in a format like cpanfile. Those organizations can use this library to assess the impact of changes in blead or a branch or of a monthly dev release on such a list.

METHODS

new()

• Purpose

  CPAN::cpanminus::reporter::RetainReports constructor.

• Arguments

      my $reporter = CPAN::cpanminus::reporter::RetainReports->new(
          force               => 1,
          build_dir           => $cpanmdir,
          build_logfile       => $log,
          'ignore-versions' => 1,
      );

  Takes a list of key-value pairs or hash. Keys may be any eligible for passing to App::cpanminus::reporter::new(). Those shown have proven to be useful for this library's author.

• Return Value

  CPAN::cpanminus::reporter::RetainReports object.

• Comments

  • Inherited from App-cpanminus-reporter.

  • Environmental Variables

    At this time it is thought that these two environmental variables should be explicitly set if either the .cpanm or the .cpanreporter directory is in a non-standard location, i.e., in a location other than directly under the user's home directory.

        local $ENV{PERL_CPANM_HOME}         = '/home/username/.cpanm';
        local $ENV{PERL_CPAN_REPORTER_DIR}  = '/home/username/.cpanreporter';

set_report_dir()

• Purpose

  Identify the directory to which reports will be written, creating it if needed.

• Arguments

      $reporter->set_report_dir($analysisdir);

  String holding path to desired directory.

• Return Value

  String holding path to desired directory.

get_report_dir()

• Purpose

  Identify the already created directory in which reports will be ridden.

• Arguments

      $self->get_report_dir();

  None.

• Return Value

  String holding path to relevant directory.

parse_uri()

• Purpose

  While parsing a build log, parse a URI.

• Arguments

      $self->parse_uri("http://www.cpan.org/authors/id/J/JK/JKEENAN/Perl-Download-FTP-0.02.tar.gz");

  String holding a URI such as the one above.

• Return Value

  True value upon success; undef otherwise.

• Comments

  • Stores the following attributes for a given CPAN distribution:

        distname        => 'Perl-Download-FTP'
        distversion     => '0.02'
        distfile        => 'JKEENAN/Perl-Download-FTP-0.02.tar.gz'
        author          => 'JKEENAN'

    These attributes can subsequently be accessed via:

        $self->distname();
        $self->distversion();
        $self->distfile();
        $self->author();

  • Limited to parsing these URI schemes:

        http https ftp cpan file

  • Overwrites App::cpanminus::reporter::parse_uri().

run()

• Purpose

  Execute a run of processing of a cpanm build log.

• Arguments

  None.

• Return Value

  None relevant.

• Comments

  • See the examples/ directory for sample reports.

  • Inherited from App-cpanminus-reporter. However, whereas that library's method composes and transmits a report to CPANtesters.org, this library's run() method generates a .json report file for each distribution analyzed and retains that on disk for subsequent processing or analysis. As such, this is the crucial difference between this library and App-cpanminus-reporter.

  • In a later version of this library we will provide a more human-friendly, plain-text version of the report.

BUGS AND SUPPORT

Please report any bugs by mail to bug-CPAN-cpanminus-reporter-RetainReports@rt.cpan.org or through the web interface at http://rt.cpan.org.

AUTHOR

    James E Keenan
    CPAN ID: JKEENAN
    jkeenan@cpan.org
    http://thenceforward.net/perl/modules/CPAN-cpanminus-reporter-RetainReports

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1). cpanm(1). cpanm-reporter(1). App::cpanminus(3). App::cpanminus::reporter(3).

cpanm CPAN::cpanminus::reporter::RetainReports

perl -MCPAN -e shell
install CPAN::cpanminus::reporter::RetainReports