New to Perl Development

If you've never patched a Perl module before, this is a guide to help you get your Perl development environment setup and learn how to work with a Perl module out of its repository.

Generally useful links for those new to Perl

• http://learn.perl.org/ has all the basics for those new to Perl.
• chromatic's Modern Perl book is free and a great introduction to programmer Perl for reals.

Setting up your Perl development environment

This isn't strictly necessary, but it will help you in the long and probably even short run.

• We highly recommend you install your own copy of Perl in your user directory with perlbrew. Different operating systems have different versions of Perl and break it in different ways. perlbrew will guarantee you have a consistent, up-to-date install of Perl. It will save you and your mentor a lot of time. Once you have perlbrew installed, run perlbrew init and follow its instructions. Then nice perlbrew install perl-5.14.2 will compile and install (in your user directory, it won't interfere with your operating system's perl) a fresh copy of Perl. nice makes sure it doesn't slow down your machine while it's doing so. It might take 10-30 minutes depending on your hardware. Make a sandwich.

• We recommend you install cpanminus which is one of the simplest and friendliest CPAN clients for installing Perl modules. perlbrew can do it for you or you can follow cpanminus' normal installation instructions.

Getting the code

For a module on Github, you'll have to clone the git repository to get a copy of the code. Please see help.github.com for more information. We also recommend the free Pro Git book written by one of the Github folks.

Satisfying the dependencies

To install a Perl module you need to first install any modules it depends on. Sometimes folks refer to this as "dependency hell". Fortunately, if you're using perlbrew and cpanminus, we can do it the easy way.

• First, cd to the source directory of the module you just cloned.

• Then run perl Build.PL which configures the module for installation. It should complain about a lot of missing modules. There's a lot of ways to resolve this, but we'll show you how to do it with cpanminus.

• cpanm --installdeps . will install all the dependencies for the Perl module whose source tree you're sitting in. Alternatively you can run perl Build installdeps.

• Run perl Build.PL again and it should be happy.

• Run perl Build to build the module.

• Run perl Build test to run the module's tests.

• It all worked? Great! You're ready to develop. If it didn't work, find someone to help.

Running the tests

While you're developing, you're going to want to run individual tests. Perl tests are just like any other Perl program with one key difference. You have to make sure the test program loads the version of the module sitting in your source directory and not one which you may have installed.

There's three ways to do this.

• perl Build test will do it for you, but it runs the whole test suite which often isn't what you want while developing.

• prove -l t/foo.t will run a single test. The -l flag tells it to use the Perl modules in lib/ first. You can also pass it the -v flag to see the exact output of the test rather than the summary provided by prove.

• perl -Ilib t/foo.t will run a single test, raw. This is the most flexible way of running the tests while developing, but it does not provide the nice summary like prove. -Ilib tells perl to look in lib/ first for modules. If you're comfortable with a debugger, you can add -d to debug the test and your changes.

For most Perl modules it is not necessary to rebuild the project between changes. For certain things in perl5i it is, mostly if you change things in bin.