CPAN-YACSmoke will try and default as much as possible, but it may be beneficial to configure some or all of the underlying options to better integrate with your infrastructure.

As of this writing you need the alpha version, [http://search.cpan.org/~rrwo/CPAN-YACSmoke-0.03_07/ 0.03_07].

When you install the distribution, also included and copied to your Perl/bin directory is yacsmoke.pl. Take a look at it to give yourself an overview of how it can be used. Its usage is:

Usage: perl yacsmoke.pl [-t|--test <distribution>] 
                        [-l|--list <list_from>:<param_name>=<param_value>]
                        [-a|--audit <audit file>]
                        [-c|--config <configuration file>]
                        [-s|--smokedb <smoke database file>]
                        [-d|--database <database>]
                        [-h|--help]

You need not include all the options, although your own configuration file is advised.

Testing Multiple Distributions

CPAN-YACSmoke tries to make the testers life a little easier. While you can test one file at a time, it can be more profitable to test multiple distributions in a test run. The default is to use the 'recent' list available from CPAN, however there are several other alternatives. You can specify which method with the 'list_from' configuration parameter or via the '--list' option to yacsmoke.pl. The currently available options are:

Recent         - installed with CPAN-YACSmoke
PlainTextList  - installed with CPAN-YACSmoke
SmokeDB        - installed with CPAN-YACSmoke
NNTP           - released as CPAN-YACSmoke-Plugin-NNTP
NNTPWeb        - released as CPAN-YACSmoke-Plugin-NNTPWeb
Outlook        - released as CPAN-YACSmoke-Plugin-Outlook
Phalanx100     - released as CPAN-YACSmoke-Plugin-Phalanax100
WebList        - released as CPAN-YACSmoke-Plugin-WebList

See the individual distribitions for further explanations of each.

The Testing Database

Internal to CPAN-YACSmoke is a database recording the basic data from all your test report results. This includes:

• distvers - distribution name and version
• grade - the class of report (see below)

Expansion of this is planned to also include:

• OS name and version
• Perl version
• halting distribution (see below)

Aborted, Ungraded and Ignored

Aside from the standard report grades of PASS, FAIL, UNKNOWN and NA, CPAN-YACSmoke also provides other situations which have caused the testing to stop.

A distribution will be graded as aborted if at any point the testing is abandoned. This could be due to a dependency failing to install, 'Out of Memory' issues and similar. In the majority of cases, this will be due to a dependency failing. As such the current distribution should be graded to enable it to be retested should the dependency be rereleased with a fix.

A distribution that is graded as ungraded, is one where a previous test result may have been incorrect, and the tester has requested that this distribution needs to be retested.

A distribution that is graded as ignored means that its test results can be ignored due to a later version having passed its test run. This grading may be removed in order to record historical evidence of broken and subsequently fixed distributions.

Configuration File

CPAN-YACSmoke comes pre-configured with a set of defaults for the easiest method of CPAN testing. However, you may wish to fine tune your testing by using a different method to gather the list of distributions to be tested, or use a different database or elect to not test certain modules due to you not having the correct 3rd party libraries installed.

To configure yacsmoke.pl you will need to create a suitable configuration file. An example of which is below:

[CONFIG]
debug=0
verbose=1
cpantest=1


allow_retries=none
suppress_extracted=1
test_max=100
fail_max=3


exclude_dists=<<HERE
Math-BigInt-GMP
HERE

The first 3 settings relate to CPANPLUS directly. They disable the debugging feature (debug=0) within CPANPLUS, but allow the messages and errors to be recorded (verbose=1). They indicate to CPANPLUS that this is a CPAN testing run(cpantest=1), so it knows not to invoke make install after testing.

The remaining settings are for configuring CPAN-YACSmoke. They tell CPAN-YACSmoke to only try to retest distributuions which have no grade recorded (allow_retries=none), and to suppress all messages regarding the extraction of the ditribution (suppress_extracted=1). Upon receipt of a list of distribution CPAN-YACSmoke will only test 100 (test_max=100) of them in a single run (this can help to reduce flooding if you plan to have several test environments). If a single distribution has several versions in the test list, it will only allow 3 failures (fail_max=3), before moving on to the next distribution. Lastly the list of distributions to exclude from testing. Each entry is a regular expression, and if any match a distribution in the test list, the distribution is ignored. In the example above, I don't have the math library gmp available, so tests would report an undeserved FAIL.

Configuration Settings

CPANPLUS configuration settings (inherited from CPANPLUS unless otherwise noted) are:

verbose
debug 
force 
cpantest
report_pass_only
prereqs
prefer_bin
prefer_makefile    - enabled by default
makeflags
makemakerflags
md5
signature
extractdir
fetchdir

CPAN::YACSmoke specific configuration settings are:

ignore_cpanplus_bugs - test distros that CPANPLUS cannot process
ignore_bad_prereqs
fail_max
exclude_dists
test_max
allow_retries
suppress_extracted
flush_flag         - used by purge()


database_type      - database plugin, default SDBM_File
database_file      - the local cpansmoke database


list_from          - list plugin required, default Recent
recent_list_age    - used with the Recent plugin 
recent_list_path   - used with the Recent plugin 


audit_log          - log file to write progress to


config_file        - an INI file with the above settings
basedir            - base directory for configuration file,
                     defaults to the home directory

All settings have defaults associated with them, but tailoring your testing can mean you can test more efficiently.

All settings can use defaults. When using the config_file setting, the INI file should contain one setting per line, except the values for the exclude_dists setting, which are laid out as:

[CONFIG]
exclude_dists=<<HERE
mod_perl
HERE

The above would then ignore any distribution that include the string 'mod_perl' in its name. This is useful for distributions which use external libraries or applications, which are not installed or for which testing is problematic.

The setting 'test_max' is used to restrict the number of distributions tested in a single run. As some distributions can take some time to be tested, it may be more suitable to run in small batches at a time. The default setting is 100 distributions.

The setting 'allow_retries' defaults to include grades of UNGRADED and ABORTED. If you wish to change this, for example to only allow grades of UNGRADED to be retried, you can specify as:

[CONFIG]
allow_retries=ungraded

Often module authors prefer to see the details of failed tests. You can make this the default setting using:

[CONFIG]
makeflags=TEST_VERBOSE=1

Note that sending verbose failure reports for packages with thousands of tests will be quite large (!), and may be blocked by mail and news servers.