NAME

    smokebrew - Automated Perl building and installation for CPAN Testers

VERSION

    version 1.02

SYNOPSIS

      smokebrew --email tester@cpan.org --builddir /home/tester/pit/build --prefix /home/tester/pit/rel \
                --perlargs "-Dusethreads" --perlargs "-Duse64bitint" --mirrors http://cpan.hexten.net/ \
                --plugin App::SmokeBrew::Plugin::CPANPLUS::YACSmoke --recent --verbose

DESCRIPTION

    smokebrew is a utility that builds, installs and configures perls for
    CPAN testing.

    It downloads, extracts, patches ( if applicable ), configures, builds,
    tests and installs perl versions and runs an specified
    App::SmokeBrew::Plugin to configure the perl installation for CPAN
    testing.

    It accepts a number of command line switches or options options
    specified in a configuration file.

COMMAND LINE SWITCHES

    --configfile FILE

      Specify a configuration file to use. See "CONFIGURATION FILE" for
      more details.

    --builddir DIRPATH

      This is a required argument. This is the directory path that
      smokebrew will use for building and configuration. If the path
      doesn't exist it will be created.

    --prefix DIRPATH

      This is a required argument. This is the directory that will be the
      root for perl installations. If the path doesn't exist it will be
      created.

        --prefix /home/cpan/pit/rel

      In /home/cpan/pit/rel there will be a perl-version for each perl that
      is installed.

        /home/cpan/pit/rel/perl-5.8.9
        /home/cpan/pit/rel/perl-5.10.0
      
        etc.

    --email EMAILADDRESS

      This is a required argument. Must be a valid email address as
      constrained by MooseX::Types::Email. This will be passed to the given
      App::SmokeBrew::Plugin when configuring the each perl for CPAN
      Testing.

    --mx MAILEXCHANGER

      This is an optional argument. Can be a FQDN, hostname or IP address
      and is a mail exchanger that should be used instead of sending CPAN
      Test reports directly to perl.org MX. This will be passed to the
      given App::SmokeBrew::Plugin when configuring the each perl for CPAN
      Testing

    --plugin PLUGIN

      This is a required argument. Specify the App::SmokeBrew::Plugin to
      use. Plugins are verified as installed by using Module::Pluggable.
      This is what will be used to configure each perl for CPAN Testing.
      You may either specify the full plugin module name eg.
      App::SmokeBrew::Plugin::CPANPLUS::YACSmoke or, for convenience,
      specify the last part of the plugin without the
      App::SmokeBrew::Plugin prefix, eg. CPANPLUS::YACSmoke.

    --perlargs FLAG

      This is an optional argument. Specify a Configure command line
      argument that should be passed through when building each perl. There
      is no need to specify -Dprefix or -Dusedevel as smokebrew handles
      these for you. This switch may be specified multiple times with
      different arguments.

        smokebrew --perlargs "-Dusethreads" --perlargs "-Duse64bitint"

      This would pass the flags for building a threaded 64bit perl to
      Configure.

      If you specify -Dusequadmath smokebrew will only build perls that
      actually support quadmath, namely perls greater than or equal to
      v5.21.4

    --mirrors URL

      This is an optional argument. Specify the URL of a CPAN mirror that
      should be used for retrieving required files during the build process
      and what will end up as the mirror list when the given
      App::SmokeBrew::Plugin is run. This switch may be specified multiple
      times with different arguments.

        smokebrew --mirrors http://cpan.hexten.net/ --mirrors http://cpan.cpantesters.org/

    --verbose

      This an optional switch. Specify if smokebrew should produce verbose
      output about what it is doing. By default it is silent.

    --noclean

      This is an optional switch. Specify whether smokebrew should clean up
      in the builddir as it processes. The default is to be tidy.

    --nozapman

      This is an optional switch. smokebrew usually removes the man pages
      that are generated by the perl installation. Specify this option if
      you wish the man pages to be retained.

    --skiptest

      This is an optional switch. Specify whether smokebrew should skip the
      make test phase of building a perl. The default is to run make test.

    --force

      This is an optional switch. By default if a perl installation already
      exists for a given perl version smokebrew will skip over the build
      and configuration for that perl. Enabling this option will make
      smokebrew zap the existing installation and build and configure
      again.

    --forcecfg

      This is an optional switch. By default if a perl installation already
      exists for a given perl version smokebrew will skip over the build
      and configuration for that perl. Enabling this option will make
      smokebrew skip the build process, but enable reconfiguration.

    --make MAKE

      This is an optional argument. Specify the make executable that should
      be used. The default is make.

    --jobs int

      This is an optional argument. Specify an integer that should be used
      with make -j to enable parallel builds. This will be ignored for when
      building any perl below v5.19.4.

    There are a number of options that allow you to specify what particular
    perl versions are installed.

    Perls older than 5.006 are not supported.

    Perl versions 5.6.0 and 5.8.0 will also be filtered out as they are
    considered troublesome.

    Without any of the following options, smokebrew will attempt to install
    all perls that are greater than or equal to 5.006 ( subject to the
    above filtering rules ).

    Available perl releases are determined by use of Module::CoreList, if
    you find that you haven't got what you consider to be a full list,
    please update Module::CoreList to latest version available from CPAN.

    --recent

      This will indicate that you wish to only install recent perls, which
      are stable perls that are greater than or equal to 5.8.9. At the time
      of writing these were:

        5.8.9, 5.10.0, 5.10.1, 5.12.0, 5.12.1, 5.12.2, 5.12.3, 5.12.4, 5.12.5, 5.14.0, 5.14.1, 5.14.2,
        5.14.3, 5.16.0, 5.16.1 and 5.16.2

    --stable

      This will indicate that you wish to only install stable perls, which
      are perl releases with an even version number.

      Examples:

        5.6.2
        5.8.9
        5.10.1
        5.12.1

    --modern

      This will indicate that you wish to only install modern perls, which
      are stable perls that are greater than or equal to 5.10.0. At the
      time of writing these were:

        5.10.0, 5.10.1, 5.12.0, 5.12.1, 5.12.2, 5.12.3, 5.12.4, 5.12.5, 5.14.0, 5.14.1, 5.14.2,
        5.14.3, 5.16.0, 5.16.1 and 5.16.2

    --latest

      This will indicate that you wish to only install the latest recent
      perls, which are stable perls that are greater than or equal to
      5.8.9. At the time of writing these were:

        5.8.9, 5.10.1, 5.12.5, 5.14.3, 5.16.2

    --devel

      This will indicate that you wish to only install development perls,
      which are perl development releases and have an odd version number.

      Examples:

        5.7.3
        5.9.5
        5.13.0

    --install

      Specify a particular version of perl that you wish to install. This
      can be of the form perl-version or version. This overrides the
      --recent, --stable and --devel switches.

      Example:

        --install perl-5.10.1
      
        --install 5.10.1

CONFIGURATION FILE

    All the command line switches may also be specifed in a configuration
    file ( except configfile for obvious reasons ).

    The configuration file is INI style format. App::SmokeBrew::IniFile a
    subclass of Config::INI::Reader is used to read the file.

    By default smokebrew looks for a directory in your HOME directory
    called .smokebrew and for a file called smokebrew.cfg within that
    directory.

    Setting the environment variable PERL5_SMOKEBREW_DIR will affect where
    smokebrew looks for the .smokebrew directory.

    Command line switches will override anything specified in the
    configuration file, including multi-value parameters. This is a feature
    of MooseX::Getopt.

 GLOBAL OPTIONS

    builddir=DIRPATH

      This is a required argument. This is the directory path that
      smokebrew will use for building and configuration. If the path
      doesn't exist it will be created.

        builddir=/home/cpan/pit/build

    prefix=DIRPATH

      This is a required argument. This is the directory that will be the
      root for perl installations. If the path doesn't exist it will be
      created.

        prefix=/home/cpan/pit/rel

    email=EMAILADDRESS

      This is a required argument. Must be a valid email address as
      constrained by MooseX::Types::Email. This will be passed to the given
      App::SmokeBrew::Plugin when configuring the each perl for CPAN
      Testing.

        email=foo@bar.com

    mx=MAILEXCHANGER

      This is an optional argument. Can be a FQDN, hostname or IP address
      and is a mail exchanger that should be used instead of sending CPAN
      Test reports directly to perl.org MX. This will be passed to the
      given App::SmokeBrew::Plugin when configuring the each perl for CPAN
      Testing

        mx=mx.foo.com

    plugin=PLUGIN

      This is a required argument. Specify the App::SmokeBrew::Plugin to
      use. Plugins are verified as installed by using Module::Pluggable.
      This is what will be used to configure each perl for CPAN Testing.
      You may either specify the full plugin module name eg.
      App::SmokeBrew::Plugin::CPANPLUS::YACSmoke or, for convenience,
      specify the last part of the plugin without the
      App::SmokeBrew::Plugin prefix, eg. CPANPLUS::YACSmoke.

        plugin=App::SmokeBrew::Plugin::CPANPLUS::YACSmoke

      or

        plugin=CPANPLUS::YACSmoke

    perlargs=FLAG

      This is an optional argument. Specify a Configure command line
      argument that should be passed through when building each perl. There
      is no need to specify -Dprefix or -Dusedevel as smokebrew handles
      these for you. This switch may be specified multiple times with
      different arguments.

        perlargs=-Dusethreads
        perlargs=-Duse64bitint

      This would pass the flags for building a threaded 64bit perl to
      Configure.

    mirrors=URL

      This is an optional argument. Specify the URL of a CPAN mirror that
      should be used for retrieving required files during the build process
      and what will end up as the mirror list when the given
      App::SmokeBrew::Plugin is run. This switch may be specified multiple
      times with different arguments.

        mirrors=http://cpan.hexten.net/
        mirrors=http://cpan.cpantesters.org/

    verbose=BOOL

      This an optional switch. Specify if smokebrew should produce verbose
      output about what it is doing. By default it is silent.

        verbose=1

    noclean=BOOL

      This is an optional switch. Specify whether smokebrew should clean up
      in the builddir as it processes. The default is to be tidy.

        noclean=1

    nozapman=BOOL

      This is an optional switch. smokebrew usually removes the man pages
      that are generated by the perl installation. Specify this option if
      you wish the man pages to be retained.

        nozapman=1

    skiptest=BOOL

      This is an optional switch. Specify whether smokebrew should skip the
      make test phase of building a perl. The default is to run make test.

        skiptest=1

    make=MAKE

      This is an optional argument. Specify the make executable that should
      be used. The default is make.

        make=gmake

    There are a number of options that allow you to specify what particular
    perl versions are installed.

    Perls older than 5.006 are not supported.

    Perl versions 5.6.0 and 5.8.0 will also be filtered out as they are
    considered troublesome.

    Without any of the following options, smokebrew will attempt to install
    all perls that are greater than or equal to 5.006 ( subject to the
    above filtering rules ).

    Available perl releases are determined by use of Module::CoreList, if
    you find that you haven't got what you consider to be a full list,
    please update Module::CoreList to latest version available from CPAN.

    recent=BOOL

      This will indicate that you wish to only install recent perls, which
      are stable perls that are greater than or equal to 5.8.9. At the time
      of writing these were:

        5.8.9, 5.10.0, 5.10.1, 5.12.0 and 5.12.1

    stable=BOOL

      This will indicate that you wish to only install stable perls, which
      are perl releases with an even version number.

      Examples:

        5.6.2
        5.8.9
        5.10.1
        5.12.1

    devel=BOOL

      This will indicate that you wish to only install development perls,
      which are perl development releases and have an odd version number.

      Examples:

        5.7.3
        5.9.5
        5.13.0

 PLUGIN CONFIGURATION

    Options to be passed to plugins may be specified under named sections
    in the configuration file.

    You may either specify the full plugin module name as the section name
    eg. App::SmokeBrew::Plugin::CPANPLUS::YACSmoke or, for convenience,
    specify the last part of the plugin without the App::SmokeBrew::Plugin
    prefix, eg. CPANPLUS::YACSmoke.

      [Random::Plugin]
    
      someopt = foobar

KUDOS

    GUGOD for perlbrew, which inspired this utility ( and obviously gave it
    its name ).

    Florian Ragwitz for assistance with coercing an arrayref of URIs.

    H.Merijn Brand for mentioning Devel::PPPort's buildperl.pl, which I
    stole for Devel::PatchPerl which smokebrew uses to patch older perls.

    Moose for making this possible.

SEE ALSO

    Module::CoreList

    MooseX::Types::Email

    App::SmokeBrew::Plugin

AUTHOR

    Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2022 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.