NAME

    brewbuild - Automate module and reverse-dependency testing, on Windows
    and Unix

NOTICE

    This is the first devel release that includes the entire remote
    dispatching/tester server distributed testing environment. Things can
    and will change in the next couple of weeks, and there are a lot of
    edge cases that don't have tests yet (so things may not work completely
    as expected yet). Once I've got a list of requirements sorted, the POD
    nice and clean, installation confirmed fully working and more testing
    done, I'll be bumping the version to 2.00

    The module containing the API for this script can be found at
    Test::BrewBuild.

    For running remote tester servers, see bbtester
    <https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbtester> for
    the script and Test::BrewBuild::Tester for its API.

    For the dispatcher service that distributes test runs to the remote
    testers, see bbdispatch
    <https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbdispatch>
    for the script, and Test::BrewBuild::Dispatch for the API.

SYNOPSIS

    You must be in the root directory of the distribution you want to test.

    Run all unit tests against all installed instances with no other
    action. Upon a FAIL, a log file will be generated in the current
    working directory named bblog/version.bblog

        brewbuild
    
        # output
    
        5.8.9 :: PASS
        5.20.3 :: FAIL
        5.22.1 :: PASS

    Run tests on the local working copy of the current module, then run all
    tests of all reverse dependencies of this module (as reported by CPAN),
    to ensure the down river modules will work with your new build. In this
    case, FAILs are stored in bblog/revdep-module-name.version.bblog

        brewbuild -R
    
        # output, in my Mock::Sub repo directory
    
        reverse dependencies: Test-BrewBuild, File-Edit-Portable,
          Devel-Examine-Subs, Devel-Trace-Subs
    
        Test::BrewBuild
        5.18.4 :: FAIL
        5.22.1 :: PASS
    
        File::Edit::Portable
        5.18.4 :: PASS
        5.22.1 :: PASS
    
        Devel::Examine::Subs
        5.18.4 :: PASS
        5.22.1 :: PASS
    
        Devel::Trace::Subs
        5.18.4 :: PASS
        5.22.1 :: PASS

    Print usage information

        brewbuild -h

    Display test platform setup instructions for Unix and Windows

        brewbuild --setup

DESCRIPTION

    This brewbuild script installed by the Test::Brewbuild module allows
    you to perform your unit tests seamlessly across all of your Perlbrew
    (Unix) or Berrybrew (Windows) Perl instances, as well as test all of
    your down-river CPAN modules that rely on your module against the
    locally updated version, with support for ExtUtils::MakeMaker,
    Module::Build and Dist::Zilla distributions.

    For Windows, you'll need to install Berrybrew (see "SEE ALSO" for
    details). For Unix, you'll need Perlbrew.

    It allows you to remove and reinstall on each test run, install random
    versions of perl and install specific versions.

    All unit tests are run against all installed perl instances, unless
    otherwise specified.

USAGE

 -o, --on

    Perl version number to run against (can be supplied multiple times).
    Can not be used on Windows at this time.

 -R, --revdep

    Run tests, install, then run tests on all CPAN reverse dependency
    modules.

 -d, --debug

    0-7, sets logging verbosity, default is 0.

 -n, --new

    How many random versions of perl to install (-1 to install all).

 -r, --remove

    Remove all installed perls (less the currently used one).

 -i, --install

    Number portion of an available perl version according to *brew
    available. Multiple versions can be sent in at once.

 -N, --notest

    Do not run tests. Allows you to --remove and --install without testing.

 -S, --save

    By default, we save logs of FAIL result logs into the bblog directory.
    With this flag, we'll save both the FAIL logs along with all the PASS
    logs as well.

 -l, --legacy

    Operate on perls less than 5.8.x. The default plugins won't work with
    this flag set if a lower version is installed.

 -p, --plugin

    Optional module name of the exec command plugin to use. You can also
    specify a file name if the module is not installed.

 -a, --args

    List of args to pass into the plugin (one arg per loop).

 -T, --selftest

    Test::BrewBuild development testing only. Prevents recursive test
    loops.

 -s, --setup

    Display test platform setup instructions.

 -h, --help

    Print out the command line usage information.

TEST PLATFORM CONFIGURATION

    Test::BrewBuild test platform configuration guide

 UNIX

    Install perlbrew and related requirements:

        cpanm App::perlbrew
        perlbrew install-patchperl
        perlbrew install-cpanm

    Install and switch to your base perl instance, and install
    Test::BrewBuild:

        perlbrew install 5.22.1
        perlbrew switch 5.22.1
        cpanm Test::BrewBuild

 WINDOWS

    Note that the key is that your %PATH% must be free and clear of
    anything Perl. That means that if you're using an existing box with
    Strawberry or ActiveState installed, you *must* remove all traces of
    them in the PATH environment variable for ``brewbuild'' to work
    correctly.

    Easiest way to guarantee a working environment is using a clean-slate
    Windows server with nothing on it. For a Windows test platform, I
    mainly used an Amazon AWS t2.small server.

    Download/install git for Windows:

        https://git-scm.com/download/win

    Create a repository directory, and enter it:

        mkdir c:\repos
        cd c:\repos

    Clone and configure berrybrew

        git clone https://github.com/dnmfarrell/berrybrew
        cd berrybrew
        bin\berrybrew.exe config (type 'y' when asked to install in PATH)

    Close the current CMD window and open a new one to update env vars

    Check available perls, and install one that'll become your core base
    install

        berrybrew available
        berrybrew install 5.22.1_64
        berrybrew switch 5.22.1_64
        close CMD window, and open new one

    Make sure it took

        perl -v

    Install Test::BrewBuild

        cpanm Test::BrewBuild

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

CONTRIBUTING

    Any and all feedback and help is appreciated. A Pull Request is the
    preferred method of receiving changes
    (https://github.com/stevieb9/p5-test-brewbuild), but regular patches
    through the bug tracker, or even just email discussions are welcomed.

BUGS

    https://github.com/stevieb9/p5-test-brewbuild/issues

SUPPORT

    You can find documentation for this script and module with the perldoc
    command.

        perldoc brewbuild
        perldoc Test::BrewBuild

    Documentation for the remote testing service script, and its API:

        perldoc bbtester
        perldoc Test::BrewBuild::Tester

    Documentation for the test dispatching script and its API:

        perldoc bbdispatch
        perldoc Test::BrewBuild::Dispatch

SEE ALSO

    Berrybrew for Windows:

    https://github.com/dnmfarrell/berrybrew

    Perlbrew for Unixes:

    http://perlbrew.pl

    Remote testing server:

    <a
    href="https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbtester">bbtester</a>

    Remote testing server API:

    Test::BrewBuild::Tester

    Dispatching to remote testers:

    See brewbuild -h, in the Dispatching Server options section.

    Dispatcher API:

    Test::BrewBuild::Dispatch

LICENSE AND COPYRIGHT

    Copyright 2016 Steve Bertrand.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.

