NAME
    CPAN::YACSmoke - Yet Another CPAN Smoke Tester

SYNOPSIS
      perl -MCPAN::YACSmoke -e test

REQUIREMENTS
    This package requires the following modules (most of which are not
    included with Perl):

      CPANPLUS
      Config::IniFiles
      File::Basename
      File::HomeDir
      File::Path
      File::Spec
      IO::File
      LWP::Simple
      Module::Pluggable
      Regexp::Assemble
      SDBM_File
      Sort::Versions
      Test::Reporter
      URI

   These dependencies (such as CPANPLUS and Test::Reporter) may require
   additional modules.

Installation
    Installation can be done using the traditional Makefile.PL or the
    newer Build.PL methods.

    Using Makefile.PL:

      perl Makefile.PL
      make
      make test
      make install

    (On Windows platforms you should use nmake instead.)

    Using Build.PL (if you have Module::Build installed):

      perl Build.PL
      perl Build
      perl Build test
      perl Build install

DESCRIPTION
    This module uses the backend of CPANPLUS to run tests on modules
    recently uploaded to CPAN and post results to the CPAN Testers list.

    It will create a database file in the .cpanplus directory which it uses
    to track tested distributions. This information will be used to keep
    from posting multiple reports for the same module, and to keep from
    testing modules that use non-passing modules as prerequisites.

    If it is given multiple versions of the same distribution to test, it
    will test the most recent version only. If that version fails, then it
    will test a previous version.

    By default it uses CPANPLUS configuration settings, although these
    can be overridden by a configuration file.

  EXPORTS
    The following routines are exported by default. They are intended to be
    called from the command-line, though they could be used from a script.

    test
          perl -MCPAN::YACSmoke -e test

          perl -MCPAN::YACSmoke
            -e test('authors/id/R/RR/RRWO/Some-Dist-0.01.tar.gz')

        Runs tests on CPAN distributions. Arguments should be paths of
        individual distributions in the author directories. If no arguments
        are given, it will download the RECENT file from CPAN and use that.

        By default it uses CPANPLUS configuration settings. If CPANPLUS is
        set not to send test reports, then it will not send test reports.

    mark
          perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01')

          perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01', 'fail')

        Retrieves the test result in the database, or changes the test
        result.

        It can be useful to update the status of a distribution that once
        failed or was untestable but now works, so as to test modules which
        make use of it.

    excluded
          perl -MCPAN::YACSmoke -e excluded('Some-Dist-0.01')

          perl -MCPAN::YACSmoke -e excluded()

	Given a list of distributions, indicates which ones would be excluded
	from testing, based on the exclude_dist list that is created.

    purge
          perl -MCPAN::YACSmoke -e purge()

          perl -MCPAN::YACSmoke -e purge('Some-Dist-0.01')

	Purges the entries from the local cpansmoke database. The criteria for
	purging is that a distribution must have a more recent version, which 
	has previously been marked as a PASS. However, if one or more 
	distributions are passed as a parameter list, those specific 
	distributions will be purged.

	If the flush_flag is set, via the config hash, to a true value, the 
	directory path created for each older copy of a distribution is 
	deleted.

    flush
          perl -MCPAN::YACSmoke -e flush()
  
          perl -MCPAN::YACSmoke -e flush('all')

          perl -MCPAN::YACSmoke -e flush('old')

	Removes unrequired build directories from the designated CPANPLUS 
	build directory. Note that this deletes directories regardless of 
	whether the associated distribution was tested.

	Default flush is 'all'. The 'old' option will only delete the older 
	distributions, of multiple instances of a distribution.

	Note that this cannot be done reliably using last access or modify 
	time, as the intention is for this distribution to be used on any OS 
	that CPANPLUS is installed on. In this case not all OSs support the 
	full range of return values from the stat function.

REVISION HISTORY
    The following changes have been made since the previous publicly
    available version:

    0.03_04 Mon Apr  4 2005
        - bugfixes
          * when a grade is not found should be listed as 'none' in test()
          * new() wasn't being passed the %config hash in mark()
          * the $dist can either be a full path or the dist name in mark()
          * uc() was unclear in purge()
          * debug call removed from purge()

    0.03_03 Mon Apr  4 2005
        - YAML is now a required module
        - renamed connect_configure, connect_cpanplus, connect_db,
          disconnect_db functions to conform to Pod::Coverage reqs
        - corrected typo in POD
        - added Pod::Coverage tests
        - removed File::Spec minimum version since it limited platforms

    0.03_02 Mon Apr  4 2005
        - added new purge() and flush() functions
        - ability to specify local database file
        - rebuilt excluded dist functions for reuse
        - added 'allow_retries' configuration setting
        - added 'flush_flag' configuration setting (used by purge())
        - distributions with .tgz and .zip extensions now also supported
        - cleaned up audit printing
        - updated POD for plugins & bug reporting
        - added examples/smoke-purge.pl script

    See the Changes file for a complete revision history.

CAVEATS
    This is a proto-type release. Use with caution and supervision.

    The current version has a very primitive interface and limited
    functionality. Future versions may have a lot of options.

    There is always a risk associated with automatically downloading and
    testing code from CPAN, which could turn out to be malicious or severely
    buggy. Do not run this on a critical machine.

    This module uses the backend of CPANPLUS to do most of the work, so is
    subject to any bugs of CPANPLUS.

    And yes, it's sorely in need of documentation.

AUTHORS
    Robert Rothenberg <rrwo at cpan.org>

    Barbie <barbie at cpan.org>, for Miss Barbell Productions,
    <http://www.missbarbell.co.uk>

COPYRIGHT AND LICENSE
    Copyright (C) 2005 by Robert Rothenberg. All Rights Reserved.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.3 or, at
    your option, any later version of Perl 5 you may have available.
