NAME

    minismokebox - a small lightweight SmokeBox

VERSION

    version 0.68

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;
       --random          - specify a random selection of dists to smoke;
       --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;
       --noepoch        - set to disable only smoking the most recent uploads;
       --perlenv        - set to enable PERL5LIB being passed to smoker process;

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 the HOME 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 to root

      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 specified minismokebox will use $^X to determine the
      current perl 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 perform package, author and phalanx 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 and STDERR 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 the
      modules/01modules.mtime.rss file instead of the default RECENT file
      to discover recent CPAN uploads.

    --noepoch

      Enabling this option will disable the use of RECENT-1x.yaml files to
      determine the very most recent uploads to smoke.

    --perlenv

      Normally minismokebox ( via POE::Component::SmokeBox::Backend ) will
      sanctify the smoker process' environment variables to remove various
      perl related variables. Enabling this option will pass PERL5LIB
      environment variable to the smoker process if it is defined. This
      could have weird side-effects, use with caution.

    --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

    --author PATTERN

      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.

    --random

      Specify that you want to smoke a random selection of 100
      distributions from the CPAN indexes.

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

    random

      Set to a true value to specify that you want to smoke a random
      selection of 100 distributions from the CPAN indexes.

        random=1

    rss

      Enabling this option will tell minismokebox to use the
      modules/01modules.mtime.rss file instead of the default RECENT file
      to discover recent CPAN uploads.

        rss=1

    noepoch

      Enabling this option will disable the use of RECENT-1x.yaml files to
      determine the very most recent uploads to smoke.

        noepoch=1

    perlenv

      Normally minismokebox ( via POE::Component::SmokeBox::Backend ) will
      sanctify the smoker process' environment variables to remove various
      perl related variables. Enabling this option will pass PERL5LIB
      environment variable to the smoker process if it is defined. This
      could have weird side-effects, use with caution.

        perlenv=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 perform package, author and phalanx 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

      This is section within the configuration file. Any key/values
      specified will be passed as environment variables to the process that
      is created by POE::Component::SmokeBox::Backend.

        [ENVIRONMENT]
        PERL5LIB=/some/random/directory/path:/oh/and/another

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.

    POE::Component::SmokeBox::Backend will santify the environment of the
    smoker process of various variables using Env::Sanctify:

          '^POE_',
          '^PERL5_SMOKEBOX',
          '^HARNESS_',
          '^(PERL5LIB|TAP_VERSION|TEST_VERBOSE)$',
          '^AUTHOR_TESTING$',
          '^PERL_TEST',

    See "CONFIGURATION FILE" for a way of propogating environment variables
    to the smoker process.

    This behaviour can also be overriden for the PERL5LIB variable only by
    using the --perlenv or perlenv configuration file option. See above for
    details.

KUDOS

    Thanks go to Ricardo SIGNES for CPAN::Mini which inspired the design of
    this script/module.

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

    CPAN::Testers

    CPANPLUS::YACSmoke

    CPAN::Reporter

    CPAN::Reporter::Smoker

    CPAN::YACSmoke

    POE::Component::SmokeBox

AUTHOR

    Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2017 by Chris Williams.

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

