NAME
minismokebox - a small lightweight SmokeBox
SYNOPSIS
minismokebox [options]
Options:
--debug - display all the output from tests as they are run;
--help - Display program usage;
--version - Display program version;
--perl PERL - specify the perl executable to use for testing;
--indices - Reload indices before proceeding with testing;
--recent - Explictly smoke recent uploads, usually the default;
--jobs FILE - Specify a file with modules to be smoked;
--backend BACKEND - specify a SmokeBox backend to use;
--author PATTERN - specify a CPAN ID to search for modules to smoke;
--package PATTERN - specify a search pattern to match against distributions;
--phalanx - smoke the Phalanx 100 distributions;
--reverse - specify that RECENT uploads are smoked in reverse order;
--url URI - The URI of a CPAN mirror to use, default is CPAN Testers FTP;
--home DIR - Set a fake HOME directory for spawned smokers to use;
--nolog - Set to disable stdout/stderr logging in jobs;
--rss - set to use the rss recent file instead of the default;
DESCRIPTION
minismokebox
is a lightweight version of SmokeBox that performs CPAN testing on a single perl
installation.
It is usually installed into a separate perl
installation than the perl
which is being tested, the system perl
for instance.
/usr/bin/minismokebox --perl /home/cpan/sandbox/perl-5.10.0/bin/perl
The above command will run minismokebox
which will obtain a list of recently uploaded distributions to CPAN and then proceed to smoke
each of these distributions against the indicated perl
.
minismokebox
supports a number of different CPAN Tester frameworks ( in POE::Component::SmokeBox parlance a backend
), currently, CPANPLUS::YACSmoke, CPAN::Reporter and CPAN::YACSmoke.
/usr/bin/minismokebox --perl /home/cpan/sandbox/perl-5.10.0/bin/perl # uses default 'CPANPLUS::YACSmoke'
/usr/bin/minismokebox --perl /home/cpan/sandbox/perl-5.10.0/bin/perl --backend CPAN::Reporter
/usr/bin/minismokebox --perl /home/cpan/sandbox/perl-5.10.0/bin/perl --backend CPAN::YACSmoke
minismokebox
will check
that the selected backend exists in the indicated perl
before proceeding with the smoke
phase. This is very simple check and does not test whether the smoke environment is properly configured to send test reports, etc. Consult the applicable documentation for instructions on how to configure the testing environment. ( See the links below in "SEE ALSO" ).
WARNING
There are risks associated with CPAN smoke testing. You are effectively downloading and executing arbitary code on your system.
Here are some tips to mitigate the risks:
- Use a
sandbox
account -
Don't run smoke tests as
root
or other priviledged user. Create a separate user account to smoke test under. For the even more paranoid you can give theHOME
directory for this user account a separate filesystem. - Use a virtualised system
-
Virtualise your testing environment with Xen, Vmware, VirtualBox, etc. If the system does get hosed you can recover it from a snapshot backup very quickly.
- Chown the
perl
installation toroot
-
Making sure that the user who is running the smoke testing can't write to the
perl
installation is a very good plan. There have been incidents in the past where a recalcitrant module has managed to trash smoke test environments. - Monitor your
TEMP
file area -
Keep an eye on the
/tmp
directory, a lot of test-suites leave droppings behind.
COMMAND LINE OPTIONS
Command line options override options given in the "CONFIGURATION FILE"
--debug
-
Turns on all output from the POE::Component::SmokeBox::Backend as distributions are smoked.
--help
-
Displays program usage and exits.
--version
-
Displays the program version and exits.
--perl PERL
-
The path to a
perl
executable to run the smoke testing against. If this isn't specifiedminismokebox
will use$^X
to determine the currentperl
and use that. --backend BACKEND
-
Specify a particular POE::Component::SmokeBox::Backend to use for smoking. This can be CPANPLUS::YACSmoke, CPAN::YACSmoke or CPAN::Reporter. The default if this isn't specified is CPANPLUS::YACSmoke.
--indices
-
Indicates that
minismokebox
should reindex the particular backend before proceeding with the smoke testing. --url URI
-
The URI of a CPAN Mirror that
minismokebox
will use to obtain the recent uploads from or performpackage
,author
andphalanx
searches against. For consistency this should really match the CPAN Mirror configured in the applicable backend you are using. --home DIR
-
The path to a directory that will become the
HOME
environment variable in spawned smoke processes. It will be created if it does not exist. --nolog
-
If enabled the
STDOUT
andSTDERR
of job output will not be logged.
The following options control where minismokebox
obtains a list of distributions to smoke. If none of these are specified the default behaviour is --recent
. These options are cumulative. For example:
minismokebox --perl /home/cpan/perl-5.10.0/bin/perl --recent --package '^POE' --author '^BI' --phalanx
This would smoke a list of recent uploads, all distributions that begin with POE
, the distributions for each CPAN author whose CPAN ID begins with BI
and a list of the Phalanx 100 distributions.
--recent
-
Explicitly tell
minismokebox
to smoke the recent uploads to CPAN. This is the default action if none of the following actions are given. --rss
-
Enabling this option will tell
minismokebox
to use themodules/01modules.mtime.rss
file instead of the defaultRECENT
file to discover recent CPAN uploads. --reverse
-
If specified
minismokebox
will smoke recent uploads in reverse order. --jobs FILE
-
Indicate a file where
minismokebox
should get a list of distributions to smoke from, eg.C/CH/CHROMATIC/Acme-Incorporated-1.00.tar.gz B/BI/BINGOS/POE-Component-IRC-5.12.tar.gz
--package PATTERN
-
Specify a string representing a package search to find distributions to smoke. The pattern is a regular expression and is applied to the package or distribution name plus version number ( the so called distvname, see CPAN::DistnameInfo ), eg.
--package '^POE' # find all distributions that begin with POE --package 'IRC' # find all IRC related distributions --package '0.01' # find all distributions that are version 0.01 --package '_\d+$' # find all development releases
-
Specify a string representing an author search to find distributions to smoke. The pattern is a regular expression and is applied to the CPAN ID of CPAN authors. eg.
--author '^BINGOS$' # find all distributions that belong to BINGOS --author '^BI' # find all distributions that belong to authors beginning with BI --author '^B' # find all distributions for the 'B' authors
--phalanx
-
Specify that you want to smoke the Phalanx '100' distributions, http://qa.perl.org/phalanx.
CONFIGURATION FILE
A number of the above options may be specified in a configuration file, minismokebox
, that is stored in the .smokebox
directory. See "ENVIRONMENT" for where the .smokebox
directory is located and how to effect its location.
Command line options will override options from the configuration file.
The configuration file is parsed using Config::Tiny.
A subset of the command line options can be specified in the configuration file:
debug
-
Set to a true value to turn on all output from the POE::Component::SmokeBox::Backend as distributions are smoked.
debug=1
indices
-
Set to a true value to indicate that
minismokebox
should reindex the particular backend before proceeding with the smoke testing.indices=1
recent
-
Set to a true value to explicitly tell
minismokebox
to smoke recent uploads to CPAN.recent=1
rss
-
Enabling this option will tell
minismokebox
to use themodules/01modules.mtime.rss
file instead of the defaultRECENT
file to discover recent CPAN uploads.rss=1
perl
-
Specify the path to the
perl
executable to use for smoke testing.perl=/home/cpan/rel/perl-5.10.0/bin/perl
backend
-
Specify the POE::Component::SmokeBox::Backend to use for smoke testing
backend=CPAN::Reporter
url
-
The URI of a CPAN Mirror that
minismokebox
will use to obtain the recent uploads from or performpackage
,author
andphalanx
searches against. For consistency this should really match the CPAN Mirror configured in the applicable backend you are using.url=http://www.cpan.org/
home
-
The path to a directory that will become the
HOME
environment variable in spawned smoke processes. It will be created if it does not exist.
ENVIRONMENT
minismokebox
uses the .smokebox
directory to locate the configuration file, minismokebox
.
This is usually located in the current user's home directory. Setting the environment variable PERL5_SMOKEBOX_DIR
will effect where the .smokebox
directory is located.
KUDOS
Thanks go to Ricardo SIGNES for CPAN::Mini which inspired the design of this script/module.
AUTHOR
Chris BinGOs
Williams <chris@bingosnet.co.uk>
LICENSE
Copyright © Chris Williams
This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.
SEE ALSO
http://www.cpantesters.org/ - CPAN Testers: Index
http://wiki.cpantesters.org/ - CPAN Testers Wiki
http://stats.cpantesters.org/ - CPAN Testers Statistics
http://lists.cpan.org/showlist.cgi?name=cpan-testers-discuss - CPAN Testers Discussion Mailing List