The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-CPANTS-Generator-0.010
River stage zero No dependents
++
/ Module::CPANTS::Generator

NAME

Module::CPANTS::Generator - Generate CPANTS statistics

SYNOPSIS

  my $cpants=Module::CPANTS::Generator->new;
  
  my $metric=$cpants->unpack($path_to_package);
  
  foreach my $testclass (@test_classes) {
      print "\trunning $testclass\n";
      $testclass->generate($metric);
  }
  
  $metric->report;

Or see examples/*.pl for some scripts

DESCRIPTION

Module::CPANTS::Generator is BETA code, so things might change in future releases.

Please note that CPAN::DistnameInfo Version 0.04 is needed, which is not released yet. You can get it from here: http://svn.mutatus.co.uk/browse/CPAN-DistnameInfo/trunk/

CPANTS consists of three basic classes, some of which require subclassing to work. There is one main object, $cpants (provided by Module::CPANTS::Generator), and one object for each distribution that is tested called $metric (provided by Module::CPANTS::Metrics). Module::CPANTS::Reporter does not create objects but uses class methods.

First, a Module:CPANTS:Generator object is created, called $cpants It contains a configuration object (AppConfig) and is responsible for loading testing and reporting modules. It might use a CPANPLUS::Backend to connect to CPAN.

Each testing module (which must be a subclass of Module:CPANTS:Generator) contains information on the tests it is going to run. From this information, $cpants calculates the total kwalitee available and generates some metadata (which test are there, what exaclty do they test).

While testing each distribution, a Metrics Object for this distribution is created. This object contains information on the distribution (name, unpacked location, etc), a link to the $cpants object (to access config values etc) and a data structure of the test results.

During and after testing, all loaded reporter modules (subclasses of M:C:Reporter) are called.

CONFIGURATION

Module:CPANTS:Generator uses AppConfig for reading command line options and config files.

From the commandline, use

  -option value

In a config file, use

  option = value

See AppConfig for detailed information.

Here is a list of options:

Please note that all CPAN-releated config values are only needed if you want to test distributions on CPAN and thus are not needed in "lint"-mode.

Boolean values

quiet

Supress output

Default: undef

force

Force testing of all distributions reported by CPANPLUS (instead of only testing previously untested distributions)

Default: undef

reload_cpan

Call reload_indices on the CPANPLUS::Backend object. This will establish a connection to your CPAN mirror and fetch a new filelist.

Default: undef

String values

temp_dir

Path to a temp directory. This shouldn't be /tmp, but a custom temp directory only used by CPANTS (as it might be deleted)

Default: catdir($FindBin::Bin,'temp')

unpack_dir

Path to a directory where all unpacked distributions will be stored. This should be on a big enough disk to handle about 3 Gigs.

Default: catdir($FindBin::Bin,'unpacked')

cpan

Path to a local CPAN mirror. I hope nobody is crazy enough to use CPANTS over the network.

Default: undef

limit

Maximum number of distributions to test. Mainly usefull when developing new tests to limit running time.

Default: undef

List values

reporter

A list of Module::CPANTS::Reporter subclasses. Do not include "Module::CPANTS::Reporter" here, it will be appended when the reporter modules are loaded.

You should add at least one Reporter module, or else you'll spend some CPU cycles for nothing...

Default: undef

tests

A list of Module::CPANTS::Generator subclasses. Do not include "Module::CPANTS::Generator" here, it will be appended when the test modules are loaded.

Add or remove tests as you wish, but keep the Init-test active, or else strange things might happen.

It's very handy to only load those testing modules you're currently developing.

Default: ['Init']

dbi_connect

DBI connect information (data source, username, password). This array will be passed as-is to DBIs connect method.

Default: undef

METHODS

Main Methods

new

Initiate a new cpants object. Configuration is set up using AppConfig.

new calls load_tests and load_reporter after setting up the object.

load_tests

Load testing modules. Called by new, so do not call it directly.

The config value reporter contains a list of testing module names. 'Module::CPANTS::Generator::' will be prepended to each module name. (eg. 'Files' is changed to 'Module::CPANTS::Generator::Files'

Each module is loaded. Each's module package global hash %kwalitee is used to generate the global kwalitee definitions and to calculate the total kwalitee available.

load_reporter

Load reporter modules. Called by new, so do not call it directly.

The config value reporter contains a list of reporter module names. 'Module::CPANTS::Reporter::' will be prepended to each module name. (eg. 'DB' is changed to 'Module::CPANTS::Reporter::DB'

Each module is loaded and the class method init called.

unpack

  my $metric=$cpants->unpack($path_to_package);

Unpack does quite a lot:

  • initiate a new Module::CPANTS::Metrics object for the to be tested package.

  • initate a new CPAN::DistnameInfo object from the package filename.

  • extract the package

  • check if the package extracts nicely

  • move the extracted package to unpack_dir

  • add some first information (size_packed, extracts_nicely, data provided by CPAN::DistnameInfo) to the metrics object

Returns a Module::CPANTS::Metrics object.

unpack_cpanplus

  my $metric=$cpants->unpack_cpanplus($module_object);

Wrapper around unpack.

$module_object must be a CPANPLUS module object.

unpack_cpanplus will use CPANPLUS::Backend to fetch the package from CPAN (hopefully from a local mirror) and call unpack on it.

Additionally, $metric->cpan_author will be set to the value of $module_object->author.

Virtual Methods

These Methods must be implemented in subclasse of Module::CPANTS::Generator

generate

This method does the actual testing and generating of data. See Module::CPANTS::Generator::Init and Module::CPANTS::Generator::Files for more info / examples.

create_db

Return a ARRAYREF containing SQL-statments to create tables that can store all information generated by the module.

Accessor Methods provided by Class::Accessor

conf

Return the AppConfig object.

You can do $cpants->conf->config_key to access config values directly.

total_kwalitee

return total wwalitee.

tests

Return arrayref of loaded test modules (Subclasses of Module::CPANTS::Generator). This are the fully qualified namespaces, i.e. Module::CPANTS::Generator::Prereq

reporter

Return arrayref of loaded reporter modules (Subclasses of Module::CPANTS::Reporter). This are the fully qualified namespaces, i.e. Module::CPANTS::Reporter::DB)

CPANTS

The CPAN Testing Service.

See http://www.pobox.com/~schwern/talks/CPANTS/full_slides/ and http://domm.zsi.at/talks/vienna_pm200309/ for more info.

SEE ALSO

Module::CPANTS::Metrics

Module::CPANTS::Reporter

TODO

  • More Tests

  • Better Tests

AUTHOR

Thomas Klausner <domm@zsi.at> http://domm.zsi.at

Please use the perl-qa mailing list for discussing all things CPANTS: http://lists.perl.org/showlist.cgi?name=perl-qa

based on work by Leon Brocard <acme@astray.com> and the original idea proposed by Michael G. Schwern <schwern@pobox.com>

LICENSE

Module::CPANTS::Generator is Copyright (c) 2003 Thomas Klausner, ZSI. All rights reserved.

You may use and distribute this module according to the same terms that Perl is distributed under.