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