Perl Module Travis-CI Helper
This is a set of utilities meant to aid in testing modules on travis-ci. It will automatically build perl if the version requested doesn't exist.
While Travis-CI provides simple testing with perl or other languages, it has several limitations to address. It only has a limited number of perl versions available, and only uses the default build options.
These helpers will build perl versions for you if they aren't available. Additional helpers will build a dist package using a newer perl than the tests are run with, or aid with installing dependencies or reporting code coverage.
The helpers can be used individually, or automatic mode can be used if using a standard testing setup.
Example Simple .travis.yml
language: perl perl: - "5.8" # normal preinstalled perl - "5.8.4" # downloads a pre-built 5.8.4 - "5.8.4-thr" # pre-built 5.8.4 with threading - "5.12.2" # builds perl 5.12.2 from source (pre-built not available) - "5.20" # installs latest perl 5.20 (if not already available) - "dev" # installs latest developer release of perl (e.g. 5.21.8) - "blead" # builds perl from git cache: directories: - $HOME/perl5 matrix: include: - perl: 5.18 env: COVERAGE=1 # enables coverage reporting (coveralls by default), # or COVERAGE=report_name to use a specific report # module allow_failures: - perl: blead # ignore failures for blead perl before_install: - eval $(curl https://travis-perl.github.io/init) --auto
This will work for most distributions. It will work with dists using a Makefile.PL, Build.PL, Dist::Zilla or Dist::Inkt.
If the specified perl version is already installed on the Travis testing machine, it will be used as is. Any requested perl version that isn't available will be built for you. Additionally, a number of commonly tested versions are pre-built and will be automatically downloaded and used to speed up testing. The pre-built perl versions are listed in the .travis.yml for the builder repo. If the patch level isn't included in the version, the latest in that series will be used. Additionally, some build flags can be specified by adding them as dash separated suffixes (e.g. 5.10.1-thr-mb).
thr Builds a perl with thread support. Controls the
dbg Builds a debugging perl. Controls the
mb Builds a perl with 64-bit and long double support. Controls the
shrplib Builds a shared libperl used by perl. Needed for some dynamic loading cases. Controls the
There are three other special versions that can be requested:
system Uses the default system perl. This can be useful if there are perl modules you want to install using apt-get.
dev Installs the latest development perl build available. This will be something like 5.21.8.
blead Installs perl from git. This is bleading-edge version of perl, and will occasionally fail to build at all. If used, it's usually recommended to list in
Control Environment Variables
There are various environment variables that will control how a build is done.
If true, coverage will be reported after running tests. When value is 1 coverage results will be submitted to Coveralls. Otherwise the value is going to be used a Devel::Cover report module name. If false, the
cpan-install --coveragecommands will be no-ops.
Defaults to false.
If true, developer prerequisites will be installed by the
cpan-install --depscommand, and the
test-filescommands will include the
xtdirectory. This will also be used by many test scripts.
Defaults to true.
Controls if the dist should be generated using a separate (more modern) perl version. This is needed if the dist generation process requires a newer perl version than is being tested. It can also help speed up the generation process if it has heavy dependencies, such as Dist::Zilla, and testing is being done on a freshly built perl.
Defaults to true.
The CPAN mirror that dependencies will be installed from.
Defaults to http://www.cpan.org/.
If set, prebuilt versions of perl will not automatically be downloaded and used.
test-fileswill divide all of the tests into partitions and return the files from one of them. This can be used to split up long testing runs to keep them under the time limits imposed by Travis-CI.
If set, then all the helper scripts will include
set +x, causing them echo all the commands that they run. This can be helpful when trying to understand problems with using these helpers.
Example Long .travis.yml
.travis.yml listed above is roughly equivalent to:
language: perl perl: - "5.8" - "5.8.4" - "5.8.4-thr" - "5.12.2" - "5.20" - "dev" - "blead" matrix: include: - perl: 5.18 env: COVERAGE=1 allow_failures: - perl: "blead" before_install: - git clone git://github.com/travis-perl/helpers ~/travis-perl-helpers - source ~/travis-perl-helpers/init - build-perl - perl -V - build-dist - cd $BUILD_DIR # $BUILD_DIR is set by the build-dist command install: - cpan-install --deps # installs prereqs, including recommends - cpan-install --coverage # installs coverage prereqs, if enabled before_script: - coverage-setup script: - prove -l -j$(test-jobs) $(test-files) # parallel testing after_success: - coverage-report
Using this form rather than
--auto allows many more parts of the process to be
Sets up the helper functions, and initializes environment variables. Accepts three options:
--perl automatically runs the build-perl command for you
--auto Does as much as possible for you. Runs build-perl, and uses other commands as appropriate to do a full build and test. If this option is used, none of the other build phases should be customized, and none of the commands should be used aside from cpan-install.
cpanmcommand will be run without the
--skip-satisfiedoption. If you are using Travis caching to cache your installed Perl prereqs, you will want to add this flag so that your local lib does not get progressively more out of date over time.
Installs the requested perl version as needed, and switches to it.
Builds a dist directory for the module. Sets the
BUILD_DIRenvironment variable to the path of the built dist. If
SPLIT_BUILDis true, the latest preinstalled perl version will used. If
SPLIT_BUILDis false, the requested perl version will be used instead.
dist.inifile exists in the repository, Dist::Zilla or Dist::Inkt will be used to generate the dist. Additional prerequisites will be installed as needed.
Makefile.PLfile exists, ExtUtils::MakeMaker's distdir command will be used.
Build.PLfile exists, Module::Build's distdir command will be used.
Installs dependencies. Dependencies can either be listed manually, or the --deps flag can be given to install all dependencies of the current dist.
This command accepts the --coverage option. If the COVERAGE environment variable is set, this will attempt to install Devel::Cover and Devel::Cover::Report::$COVERAGE (Coveralls when value is 1). If the environment variable is not set, does nothing.
Finally, you can pass --update-prereqs to make this script run without passing
Outputs either "t xt" normally, or just "t" if the AUTHOR_TESTING environment variable is set to 0.
Outputs all of the test files found in the directories returned from
TEST_PARTITIONare set, the tests are divided into
TEST_PARTITIONSequal sized groups, and group
TEST_PARTITIONwill be returned.
Outputs the recommended number of parallel test runs to use. This will be calculated based on the number of CPUs available. If
COVERAGEis true, it will be 1, as Devel::Cover does not yet cope well with parallel testing.
Sets up the environment to record coverage data when running tests. Does nothing if
Outputs a coverage report. If Devel::Cover::Report::$COVERAGE is available, it will use the corresponding report module. When set to 1 default module name is Coveralls. Does nothing if
Activates a local::lib directory. Without a parameter, creates a new local::lib directory and activates it. This is used by
Dist::Zilladistribution, and can be valuable if you need to isolate the prereqs you are installing from the core modules. Any parameters given are taken as names of predefined local::libs to load. For example,
local-lib dzilcan save a lot of time for Dist::Zilla based modules. If you specified a prebuilt local::lib there is no need to give it again. If you do want further local::libs, you can give them to this command and they will be downloaded if pre-built, or built if not, and added to the library path. This is taken care of by the
A number of predefined local::lib directories are available for use. Pre-built perl versions will also include pre-built local::lib directories. If there is no pre-built copy of the local::lib available, it will be built when requested. The list of available pre-built versions of Perl is available here. To use one of these, specify like this:
perl: - "5.6.2@moo" - "5.8.4@moo"
Travis-CI will attempt to switch to the specified perl version, and report the
perl --version. If the perl version specified isn't one of the
prebuilt options, this will result in an error and mismatched version
information. These can be ignored. The build will continue, allowing the
build-perl command to build and switch to the requested version. It is
recommended to include
perl -V after
build-perl, so the build details of
the perl being used will be included in the build log.