NAME
    CPAN::Reporter::Smoker - Turnkey CPAN Testers smoking

VERSION
    version 0.29

SYNOPSIS
         $ perl -MCPAN::Reporter::Smoker -e start

DESCRIPTION
    Rudimentary smoke tester for CPAN Testers, built upon CPAN::Reporter.
    Use at your own risk. It requires a recent version of CPAN::Reporter to
    run.

    Currently, CPAN::Reporter::Smoker requires zero independent
    configuration; instead it uses configuration settings from CPAN.pm and
    CPAN::Reporter.

    Once started, it retrieves a list of distributions from the configured
    CPAN mirror and begins testing them in reverse order of upload. It will
    skip any distribution which has already had a report sent by
    CPAN::Reporter.

    Features (or bugs, depending on your point of view):

    *   No configuration needed

    *   Tests each distribution as a separate CPAN process -- each
        distribution has prerequisites like build_requires satisfied from
        scratch

    *   Automatically checks for new distributions every twelve hours or as
        otherwise specified

    *   Continues until interrupted with CTRL-C

    *   Checks CPAN.pm "distroprefs" to see if distributions should be
        skipped (before handing off to CPAN)

    Current limitations:

    *   Does not attempt to retest distributions that had reports discarded
        because of prerequisites that could not be satisfied

    *   Does not test trial version if there is no non-trial version

  WARNING -- smoke testing is risky
    Smoke testing will download and run programs that other people have
    uploaded to CPAN. These programs could do anything to your system,
    including deleting everything on it. Do not run CPAN::Reporter::Smoker
    unless you are prepared to take these risks.

USAGE
  "start()"
    Starts smoke testing using defaults already in CPAN::Config and
    CPAN::Reporter's .cpanreporter directory. Runs until all distributions
    are tested or the process is halted with CTRL-C or otherwise killed.

    "start()" supports several optional arguments:

    *   "clean_cache_after" -- number of distributions that will be tested
        before checking to see if the CPAN build cache needs to be cleaned
        up (not including any prerequisites tested). Must be a positive
        integer. Defaults to 100

    *   "list" -- if provided, this list of distributions will be tested
        instead of all of CPAN. May be a reference to an array of
        distribution names or may be a filename containing one distribution
        name per line. Distribution names must be of the form
        'AUTHOR/Dist-Name-0.00.tar.gz'

    *   "restart_delay" -- number of seconds that must elapse before
        restarting smoke testing. This will reload indices to search for new
        distributions and restart testing from the most recent distribution.
        Must be a positive integer; Defaults to 43200 seconds (12 hours)

    *   "skip_dev_versions" -- if true, unindexed distributions will not be
        tested. Valid values are 0 or 1. Defaults to 0.

    *   "set_term_title" -- toggle for whether the terminal titlebar will be
        updated with the distribution being smoke tested and the starting
        time of the test. Helps determine if a test is hung and which
        distribution might be responsible. Valid values are 0 or 1. Defaults
        to 1

    *   "status_file" -- during testing, the name of the distribution under
        test and a timestamp are written to this file. The file is removed
        after the test is complete. This helps identify a problem
        distribution if testing hangs or crashes the computer. If the
        argument includes a path, all directories to the file must exist.
        Defaults to "smoker-status-$$.txt" in File::Spec->tmpdir.

    *   "install" -- toggle for whether the distribution should be installed
        after successful testing. Can be useful to avoid prerequisite
        re-building and growing PERL5LIB for the cost of disk space used for
        installed modules. Valid values are 0 or 1. Defaults to 0

    *   "reverse" -- toggle the order in which releases are tested. When set
        to 1, testing starts from the older release not the most recent one
        (or the last distribution if --list is provided). Valid values are 0
        or 1. Defaults to 0

    *   "random" -- toggle whether to randomize distribution test order.
        When set to 1, the list of releases is shuffled. Valid values are 0
        or 1. Defaults to 0

    *   "force_trust" -- toggle whether to override CPAN's
        "trust_test_report_history" option. When set to 1,
        "trust_test_report_history" is set to 1. When set to 0,
        "trust_test_report_history" is left alone and whatever the user has
        configured for their CPAN client is used. Valid values are 0 or 1.
        Defaults to 0

    *   "reload_history_period" -- after this period in seconds, history of
        modules smoked will be reloaded when possible. Default value 1800
        seconds (30 minutes).

HINTS
  Selection of distributions to test
    Only the most recently uploaded developer and normal releases will be
    tested, and only if the developer release is newer than the regular
    release indexed by PAUSE.

    For example, if Foo-Bar-0.01, Foo-Bar-0.02, Foo-Bar-0.03_01 and
    Foo-Bar-0.03_02 are on CPAN, only Foo-Bar-0.02 and Foo-Bar-0.03_02 will
    be tested, and in reverse order of when they were uploaded. Once
    Foo-Bar-0.04 is released and indexed, Foo-Bar-0.03_02 will not longer be
    tested.

    To avoid testing script or other tarballs, developer distributions
    included must have a base distribution name that resembles a
    distribution tarball already indexed by PAUSE. If the first upload of
    distribution to PAUSE is a developer release -- Baz-Bam-0.00_01.tar.gz
    -- it will not be tested as there is no indexed Baz-Bam appearing in
    CPAN's 02packages.details.txt file.

    Unauthorized tarballs are treated like developer releases and will be
    tested if they resemble an indexed distribution and are newer than the
    indexed tarball.

    Perl, parrot, kurila, Pugs and similar distributions will not be tested.
    The skip list is based on CPAN::Mini and matches as follows:

         qr{(?:
               /(?:emb|syb|bio)?perl-\d
             | /(?:parrot|ponie|kurila|Perl6-Pugs)-\d
             | /perl-?5\.004
             | /perl_mlb\.zip
         )}xi,

    Bundles and mod_perl distributions will also not be tested, though
    mod_perl is likely to be requested as a dependency by many modules. See
    the next section for how to tell CPAN.pm not to test certain
    dependencies.

  Skipping additional distributions
    If certain distributions hang, crash or otherwise cause trouble, you can
    use CPAN's "distroprefs" system to disable them. If a distribution is
    disabled, it won't be built or tested. If a distribution's dependency is
    disabled, a failing test is just discarded.

    The first step is configuring a directory for distroprefs files:

         $ cpan
         cpan> o conf init prefs_dir
         cpan> o conf commit

    Next, ensure that either the YAML or YAML::Syck module is installed.
    (YAML::Syck is faster). Then create a file in the "prefs_dir" directory
    to hold the list of distributions to disable, e.g. call it
    "disabled.yml"

    In that file, you can add blocks of YAML code to disable distributions.
    The match criteria "distribution" is a regex that matches against the
    canonical name of a distribution, e.g. "AUTHOR/Foo-Bar-3.14.tar.gz".

    Here is a sample file to show you some syntax (don't actually use these,
    though):

         ---
         comment: "Tests take too long"
         match:
             distribution: "^DAGOLDEN/CPAN-Reporter-\d"
         disabled: 1
         ---
         comment: "Skip Win32 distributions"
         match:
             distribution: "/Win32"
         disabled: 1
         ---
         comment: "Skip distributions by Andy Lester"
         match:
             distribution: "^PETDANCE"
         disabled: 1

    Please note that disabling distributions like this will also disable
    them for normal, non-smoke usage of CPAN.pm.

    One distribution that I would recommend either installing up front or
    else disabling with distroprefs is mod_perl, as it is a common
    requirement for many Apache:: modules but does not (easily) build and
    test under automation.

         ---
         comment: "Don't build mod_perl if required by some other module"
         match:
             distribution: "/mod_perl-\d"
         disabled: 1

    Distroprefs are more powerful than this -- they can be used to automate
    responses to prompts in distributions, set environment variables,
    specify additional dependencies and so on. Read the docs for CPAN.pm for
    more and look in the "distroprefs" directory in the CPAN distribution
    tarball for examples.

  Using a local CPAN::Mini mirror
    Because distributions must be retrieved from a CPAN mirror, the smoker
    may cause heavy network load and will repetitively download common build
    prerequisites.

    An alternative is to use CPAN::Mini to create a local CPAN mirror and to
    point CPAN's "urllist" to the local mirror.

         $ cpan
         cpan> o conf urllist unshift file:///path/to/minicpan
         cpan> o conf commit

    However, CPAN::Reporter::Smoker needs the "find-ls.gz" file, which
    CPAN::Mini does not mirror by default. Add it to a .minicpanrc file in
    your home directory to include it in your local CPAN mirror.

         also_mirror: indices/find-ls.gz

    Note that CPAN::Mini does not mirror developer versions. Therefore, a
    live, network CPAN Mirror will be needed in the urllist to retrieve
    these.

    Note that CPAN requires the LWP module to be installed to use a local
    CPAN mirror.

    Alternatively, you might experiment with the alpha-quality release of
    CPAN::Mini::Devel, which subclasses CPAN::Mini to retrieve developer
    distributions (and find-ls.gz) using the same logic as
    CPAN::Reporter::Smoker.

  Timing out hanging tests
    CPAN::Reporter (since 1.08) supports a 'command_timeout' configuration
    option. Set this option in the CPAN::Reporter configuration file to time
    out tests that hang up or get stuck at a prompt. Set it to a high-value
    to avoid timing out a lengthy tests that are still running -- 1000 or
    more seconds is probably enough.

    Warning -- on Win32, terminating processes via the command_timeout is
    equivalent to SIGKILL and could cause system instability or later
    deadlocks

    This option is still considered experimental.

  Avoiding repetitive prerequisite testing
    Because CPAN::Reporter::Smoker satisfies all requirements from scratch,
    common dependencies (e.g. Class::Accessor) will be unpacked, built and
    tested repeatedly.

    As of version 1.92_56, CPAN supports the "trust_test_report_history"
    config option. When set, CPAN will check the last test report for a
    distribution. If one is found, the results of that test are used instead
    of running tests again.

         $ cpan
         cpan> o conf init trust_test_report_history
         cpan> o conf commit

  Avoiding repetitive prerequisite builds (EXPERIMENTAL)
    CPAN has a "build_dir_reuse" config option. When set (and if a YAML
    module is installed and configured), CPAN will attempt to make build
    directories persistent. This has the potential to save substantial time
    and space during smoke testing. CPAN::Reporter::Smoker will recognize if
    this option is set and make adjustments to the test process to keep
    PERL5LIB from growing uncontrollably as the number of persistent
    directories increases.

    NOTE: Support for "build_dir_reuse" is highly experimental. Wait for at
    least CPAN version 1.92_62 before trying this option.

         $ cpan
         cpan> o conf init build_dir_reuse
         cpan> o conf commit

  Stopping early if a prerequisite fails
    Normally, CPAN.pm continues testing a distribution even if a
    prerequisite fails to build or fails testing. Some distributions may
    pass their tests even without a listed prerequisite, but most just fail
    (and CPAN::Reporter discards failures if prerequisites are not met).

    As of version 1.92_57, CPAN supports the "halt_on_failure" config
    option. When set, a prerequisite failure stops further processing.

         $ cpan
         cpan> o conf init halt_on_failure
         cpan> o conf commit

    However, a disadvantage of halting early is that no DISCARD grade is
    recorded in the history. The next time CPAN::Reporter::Smoker runs, the
    distribution will be tested again from scratch. It may be better to let
    all prerequisites finish so the distribution can fail its test and be
    flagged with DISCARD so it will be skipped in the future.

  CPAN cache bloat
    CPAN will use a lot of scratch space to download, build and test
    modules. Use CPAN's built-in cache management configuration to let it
    purge the cache periodically if you don't want to do this manually. When
    configured, the cache will be purged on start and after a certain number
    of distributions have been tested as determined by the
    "clean_cache_after" option for the "start()" function.

         $ cpan
         cpan> o conf init build_cache scan_cache
         cpan> o conf commit

  CPAN verbosity
    Recent versions of CPAN are verbose by default, but include some lesser
    known configuration settings to minimize this for untarring
    distributions and for loading support modules. Setting the verbosity for
    these to 'none' will minimize some of the clutter to the screen as
    distributions are tested.

         $ cpan
         cpan> o conf init /verbosity/
         cpan> o conf commit

  Saving reports to files instead of sending directly
    In some cases, such as when smoke testing using a development or
    prerelease toolchain module like Test-Harness, it may be preferable to
    save reports to files in a directory for review prior to submitting
    them. To do this, manually set the "transport" option in your
    CPAN::Reporter config file to use the Test::Reporter::Transport::File
    transport.

         transport=File /path/to/directory

    After review, send saved reports using Test::Reporter:

         Test::Reporter->new()->read($filename)->send()

ENVIRONMENT
    Automatically sets the following environment variables to true values
    while running:

    *   "AUTOMATED_TESTING" -- signal that tests are being run by an
        automated smoke testing program (i.e. don't expect interactivity)

    *   "PERL_MM_USE_DEFAULT" -- accept ExtUtils::MakeMaker prompt()
        defaults

    *   "PERL_EXTUTILS_AUTOINSTALL" -- set to '--defaultdeps' for default
        dependencies

    The following environment variables, if set, will modify the behavior of
    CPAN::Reporter::Smoker. Generally, they are only required during the
    testing of CPAN::Reporter::Smoker

    *   "PERL_CR_SMOKER_RUNONCE" -- if true, "start()" will exit after all
        distributions are tested instead of sleeping for the "restart_delay"
        and then continuing

    *   "PERL_CR_SMOKER_SHORTCUT" -- if true, "start()" will process
        arguments (if any) but will return before starting smoke testing;
        used for testing argument handling by "start()"

BUGS
    Please report any bugs or feature using the CPAN Request Tracker. Bugs
    can be submitted through the web interface at
    <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Reporter-Smoker>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    *   CPAN

    *   CPAN::Reporter

    *   CPAN::Testers

    *   CPAN::Mini

    *   CPAN::Mini::Devel

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/cpan-testers/CPAN-Reporter-Smoker/issues>. You will
    be notified automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/cpan-testers/CPAN-Reporter-Smoker>

      git clone https://github.com/cpan-testers/CPAN-Reporter-Smoker.git

AUTHOR
    David Golden <dagolden@cpan.org>

CONTRIBUTORS
    *   Alexandr Ciornii <alexchorny@gmail.com>

    *   Christian Walde <walde.christian@googlemail.com>

    *   gregor herrmann <gregoa@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2017 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004