Try Travis CI with your CPAN distributions
Travis is a continuous integration (CI) platform for github users, which is free to use. You can set it up so that every time you push one of your CPAN distributions to github, Travis will test it against different versions of Perl.
I've only just started playing with Travis, but I can already see benefits for using it in parallel with CPAN Testers. Why not give it a go on CPAN Day? :-)
Signing up for Travis
You need to have a github account, so once you've got one of those, go to travis-ci.org, and click on the link in the top right-hand corner of the page:
If you've recently logged in to Github, this will be automatic, otherwise you'll have to enter your github username and password.
Enabling Travis for one of your repositories
By default Travis won't look at your repositories — you need to enable Travis on a per-repository basis. In the sidebar on the left, click on the '+' button:
The sidebar will now show all the accounts / projects that you have on github, and the right-hand side will be a list of your repositories. Scroll down to the distribution you want to enable. I want to enable it for my Lingua-EN-Numbers and Lingua-EN-Fractions distributions.
Next to each distribution is a clunky-looking faux switch. Clicking on it will change it to the ON position:
Nothing will happen yet — it will run next time you push a change to github. But before you do that, you need to add a Travis config file to your repository.
Configuring your CPAN distribution
If you're using a Makefile.PL or Build.PL, then it's easy to get started. Things are a little more hairy if you're using Dist::Zilla, because Travis doesn't support DZ yet.
Makefile.PL and Build.PL
Add a file .travis.yml to your distribution:
language: perl perl: - "5.18" - "5.16" - "5.14" - "5.12" - "5.10"
This tells Travis to test your distribution with the versions of Perl listed. Having committed this file, when you push it to github, Travis will run the following for each version of Perl listed:
perl Makefile.PL && make test
Or if your dist has a Build.PL, it will run:
perl Build.PL && ./Build test
In your travis home page, you'll eventually see progress as Travis picks up your module and builds / tests it. When it's finished, it will email you the results.
There are several approaches that DZ users can take, you won't be surprised to hear.
The simplest involves making sure that your repository has a Makefile.PL in the top directory. You do this using Ryan Thompson's CopyFilesFromBuild plugin, adding the following to your dist.ini:
[CopyFilesFromBuild] copy = Makefile.PL [GatherDir] exclude_filename = Makefile.PL
You need to exclude Makefile.PL from GatherDir otherwise dzil will whine at you. If you're using the Basic bundle, you'll need to do something like this:
[@Filter] -bundle = @Basic -remove = GatherDir [GatherDir] exclude_filename = Makefile.PL [CPANFile] [CopyFilesFromBuild] copy = Makefile.PL
Which is a bit messy, I'll grant you.
You can see this approach used in my Lingua-EN-Fractions repo.
When you run dzil build now, it will copy the Makefile.PL from your build directory, to the top directory. You need to add and commit this to your repository, and will need to commit it every time it changes, which is a mild pain.
Note: this approach works if you're using "standard Dist::Zilla" stuff, including version injection. For example if you've got [@Basic] in your dist.ini, then you're fine.
The next approach uses a similar technique, but instead of copying Makefile.PL to the top directory, you generate a cpanfile for your dist, and get Travis to test your dist using prove, rather than make test.
First, add the following lines to your dist.ini:
[CPANFile] [CopyFilesFromBuild] copy = cpanfile [GatherDir] exclude_filename = cpanfile
The CPANFile plugin generates a cpanfile for your distribution, and then we use CopyFilesFromBuild to copy the cpanfile to the top directory. You need to add and commit the cpanfile.
Next, you create your .travis.yml:
language: perl script: prove -lr t install: - cpanm -n -q --skip-satisfied --installdeps . perl: - "5.18" - "5.16" - "5.14" - "5.12" - "5.10"
This uses cpanm to install the dependencies for your distribution; it is this step that requires the cpanfile. Then the script line says that instead of make test, Travis should run:
prove -lr t
With this approach, the cpanfile will probably change less often than the Makefile.PL generated by DZ, but it does mean that all your tests have to work under prove.
You can see this approach used in my Module-Path repo.
More advanced users of Travis generally use HAARG's Travis-CI helper scripts. For example, look at this .travis.yml.
Travis is a useful resource for open source developers who are using github. You might wonder whether you need it, given we have CPAN Testers. CPAN Testers will test your distribution on a wider range of operating systems and versions of Perl, but while you get your first results within a few hours, it can take up to 8 days to get full coverage. You can use Travis to get much quicker test results against a good range of Perl versions. Once Travis is happy, you can then release to PAUSE.
As an added bonus, if someone sends you a pull request, then Travis will run a test with their request merged, so you get some early testing.
I've barely scratched the surface here; to learn more:
- Dave Cross gave a talk on Github, Travis & Perl at London.pm recently;
- FREW wrote a blog post about Travis and Perl.
- The Travis documentation has a page on Travis for Perl programmers.
Thanks to DAGOLDEN for explaining a lot of this to me, and KENTNL, who helped me realise there is a lot more to Travis :-) And OALDERS who was a guinea-pig, and pointed out a problem with my first solution.
Thanks for your excellent series of CPANism HOWTOs.
My workflow still provides this all, but is a lot easier. Using Dist::Milla by Miyagawa is the secret.
Helmut: you've still got time to get in your own "Try Dist::Milla on CPAN Day" post :-)
I follow these steps to use Travis with Dist::Zilla:
- Add build/master branch to github.com
- On .travis.yml:
except = ^\.travis.yml
Master branch remains clean, while build/master branch contains needed files.
Does any one have a good suggestion for including the travis-ci build image in POD I have see a markdown example :
I remembered seeing this in some of INGY's modules.
Have a look at the source for the YAML module, for example:
Ugh. Go look at the source of YAML's pod -- I can't edit that comment to fix the quoting, sorry. Look for the "=for html" near the top of the pod.