New to Perl Development
Clone this wiki locally
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 initand follow its instructions. Then
nice perlbrew install perl-5.14.2will compile and install (in your user directory, it won't interfere with your operating system's perl) a fresh copy of Perl.
nicemakes 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.
cdto the source directory of the module you just cloned.
perl Build.PLwhich 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.
perl Build.PLagain and it should be happy.
perl Buildto build the module.
perl Build testto 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 testwill do it for you, but it runs the whole test suite which often isn't what you want while developing.
prove -l t/foo.twill run a single test. The
-lflag tells it to use the Perl modules in
lib/first. You can also pass it the
-vflag to see the exact output of the test rather than the summary provided by prove.
perl -Ilib t/foo.twill 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.
perlto look in
lib/first for modules. If you're comfortable with a debugger, you can add
-dto 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