NAME
smokebrew - Automated Perl building and installation for CPAN Testers
VERSION
version 0.52
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.
--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.
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) 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.