Perl Crash Course: Pragmas, Perl Modules, and CPAN

About Perl Pragmas, Modules, and CPAN - the Comprehensive Perl Archive Network.

Share This Post

I always like to say that 90% of Perl is its modules. Back in 2000 when I was working as a junior Perl programmer I was asked to write a web application that, among other things, could send contact messages through email. Unfortunately, I never had anyone to really teach me the Path of Perl – I only relied on Learning Perl by Randall Schwartz, and whatever I could find on the net. I had a really hard time with that application, mainly because I didn’t know about Perl modules, MySQL and SQL language. Had I been familiar with at least the Perl modules part, I wouldn’t have had to spend 8 days and nights in the office (including my birthday). I didn’t even know how to use strict; at the time! Keep reading if use strict; makes no sense to you.

Being the extensible and flexible language that it is, Perl provides us with some safeguards and helpers to assist in avoiding what happened to me (I wish I knew that back then). The first of which I’ll talk about is Pragmas.


Pragmas are special modules that come installed by default in every Perl distribution. They tell the interpreter of how it is supposed to act. To turn them on, all you have to do is call the special word use with the appropriate Pragma. To turn them off, call no and the Pragma in question. The most common and powerful Pragma is, in my opinion, strict (hence the name of this blog: use strict;).

Strict tells the Perl interpreter that all variables must be declared and tightens up security a notch. To use strict; you have to have at least working knowledge of lexical variables. It takes a while to getting used to at first, but once you’re hooked, you won’t know how you could possibly have written Perl programs without it before (I know I don’t).


$var = 1; # OK
use strict;
$var1 = 2; # compile time error

In our example above, Perl will refuse to run, raising a compile time error like such:

Global symbol “$var1” requires explicit package name at line 5.
Execution of aborted due to compilation errors.

That’s strict in effect. Notice that $var was not cited, since strict was only enforced below it. In order to bypass that error, we should have declared our variable with either my, our, or local – depending on the need. my is the most common. Look up “Packages, Namespaces, and Lexical scopes” for more on those 3 operators.


$var = 1; # OK
use strict;
my $var1 = 2; # OK

use strict; is so important that it is usually the second line of code in any decent Perl program – the first line being the shebang.

If you need to turn off strict for one reason or another, you can do so with the key word no.


use strict;
my $var = 1; # OK
no strict;
$var1 = 2; # also OK

When writing your Perl programs, it’s also good to turn on warnings and diagnostics. warnings will complain about possible problems such as useless uses of certain functions. diagnostics, on the other hand, will throw you a truckload of information regarding errors. It’s a good place to start when you’re stumped.

Perl Modules

Perl modules are pieces of code or packages that can be imported into your script with the keyword use in the same way as Pragmas. They can be Object Oriented, Procedural, or both. I will not discuss how to write a module in this post, but I will tell you where to find them for download and how to install them.

My all time favorite module is Data::Dumper. So I will use it in the following examples. The funny :: between Data and Dumper is kind of like a directory separator. The module Dumper resides in the directory Data, found in one of the paths configured in the Perl config files or the PERL5LIB environmental variable (which set the @INC array).

Data::Dumper comes installed by default, along with hundreds other modules that the developers deemed worthy. To test that your Perl distro has it, run the following command in a command line:

$ perl -MData::Dumper -e 'print "OK\n"'

You’ll most definitely see the OK being printed on your screen. The command passes 2 parameters to the Perl interpreter: -M which tells it to load a module (in this case Data::Dumper – no spaces between -M and the module name, or you’ll get a “missing argument” error), and -e which tells it to execute a piece of code (we told it to print OK, but any valid piece of code would do).

Look at what would have happened if we tried to load a module that wasn’t installed:

$ perl -Maaaa -e 'print "OK\n"'
Can’t locate in @INC (@INC contains: /usr/lib/perl5/5.10/i686-cygwin /usr/lib/perl5/5.10 /usr/lib perl5/site_perl/5.10/i686-cygwin /usr/lib/perl5/site_perl/5.10 /usr/lib/perl5/vendor_perl/5.10/i686-cygwin /usr/lib/perl5/vendor_perl/5.10 /usr/lib/perl5/vendor_perl/5.10 /usr/lib/perl5/site_perl/5.8 /usr/lib/perl5/vendor_perl/5.8 .).
BEGIN failed–compilation aborted.

To install a module, you can do it the hard way or the easy way. Some modules are harder than others, so I’ll stick with the easier ones for now. Let’s start with the hard way.

First, you should know where to find your module. CPAN – The Comprehensive Perl Archive Network is the place to go to get your modules. It has a handy search engine which will search through almost 16000 modules at the time of this writing (5/2009). There you will find code ranging from the most trivial to the craziest needs. If there’s one thing that CPANs contributors don’t lack, it’s creativity (that’s a compliment).

Enter a keyword in the search engine and it will list all relative modules. Click on the link to the one that interests you most. You will be shown its documentation in POD (Plain Old Documentation) format. That’s the data you will most likely need to learn how to use your module. It should also be the most up-to-date information, since it’s kept by its authors.

At the top of the POD screen, you’ll see a breadcrumb set of links showing the Author’s name, the module’s distribution name and version, and the module name itself:

Ilya Martynov > Data-Dumper-2.121 > Data::Dumper

Click on the link for the module’s distribution name and version, to go to the distribution details screen. You will see lots of information about the module and its sub-modules, but what should concern you right now is the download link next to the release name. Click on it and download the module tarball.

Now this is where I halt and tell you that potential headaches lie ahead. There are basically 2 kinds of modules: PurePerl ones and C-based ones. PurePerl modules are just that – modules that are solely written in Perl. The vast majority of modules, however, are written in C with bindings special for Perl. Those usually have to be compiled and as such, need a C/C++ compiler and a make program. The good news is that most *nix systems come with those tools already installed or readily available. Windows systems, however, require that you install nmake and preferably Microsoft Visual C++. Check out my post about installing MQSeries module on Windows for more information on how to get Microsoft Visual C++

Back to installing the module…

Unpack your module in some directory where you have full access. I like to keep an untouched copy of the tarball, by reading the gunzipped contents and throwing it to the screen with the -c option, and piping it to tar with xvf - parameters:

gunzip -c tarball.tar.gz | tar -xvf -

You’ll end up with a directory having the name of your distribution. Go in there and read all README files you can find. Read the INSTALL files if any.

One of the files you’ll see in the directory is Makefile.PL. That’s the kickoff file for the installation. It takes the following optional parameters: PREFIX, LIB, and INC, and creates a makefile tailor made for your system. It’s important to set the PREFIX parameter if you want the module installed in a place other than the default. LIB and INC point to the C lib and include directories, respectively.

Now that you have your makefile, it’s just a matter of running make, make test, and finally make install. Depending on the module, you should have no issues whatsoever. Other more “sensitive” modules, however, often require hours of work and even some tweaking of the makefiles by hand. DBD::Oracle is by far the craziest module I’ve ever had to install. In some machines it’s a piece of cake, and others it manages to amuse with the amount of errors it pulls out of the hat. Anyway…

That was the hard way. Now for the easy way.


If you’re finding it strange to see the CPAN title here when I’ve already talked about it above, don’t worry – I’m talking about the application CPAN and not the website.

Perl comes with the CPAN module installed, and most of the time it also creates a script in the bin directory called cpan. It’s an interactive shell that allows you to fetch information regarding authors and modules, and also allows you to install modules without having to go through the whole process of downloading the distribution, unpacking, etc.

Start up the CPAN application by calling

$ perl -MCPAN -e shell

If it’s the very first time you call it, you will be promped to answer a series of questions. Sticking to the default values is almost always OK. One of the first questions you will be asked is if you want CPAN to configure everything automatically. I recommend against it unless you know that the defaults are correct and will enable you to successfully install modules. And if you know that, then you probably already know how to use the CPAN application and this post has nothing new. 🙂

Once the questions have been answered, you will be presented with a cpan prompt. Type ? to know what options you have.

cpan[1]> ?
Display Information                                                (ver 1.9205)
 command  argument          description
 a,b,d,m  WORD or /REGEXP/  about authors, bundles, distributions, modules
 i        WORD or /REGEXP/  about any of the above
 ls       AUTHOR or GLOB    about files in the author's directory
    (with WORD being a module, bundle or author name or a distribution
    name of the form AUTHOR/DISTRIBUTION)

Download, Test, Make, Install...
 get      download                     clean    make clean
 make     make (implies get)           look     open subshell in dist directory
 test     make test (implies make)     readme   display these README files
 install  make install (implies test)  perldoc  display POD documentation

 r        WORDs or /REGEXP/ or NONE    report updates for some/matching/all modu
 upgrade  WORDs or /REGEXP/ or NONE    upgrade some/matching/all modules

 force  CMD    try hard to do command  fforce CMD    try harder
 notest CMD    skip testing

 h,?           display this menu       ! perl-code   eval a perl command
 o conf [opt]  set and query options   q             quit the cpan shell
 reload cpan   load again      reload index  load newer indices
 autobundle    Snapshot                recent        latest CPAN uploads

Use o conf to display the parameters to which you answered all those questions. You can change them with o conf as well. If you didn’t enable auto-commit before, you will have to call o conf commit to save your changes for use in future sessions.

o conf http_proxy ""

The m command allows you to fetch information regarding a certain module.

cpan[2]> m Data::Dumper
.... Possibly some data about fetching updated files from the internet here ....
Module id = Data::Dumper
    DESCRIPTION  Convert data structure into perl code
    CPAN_USERID  GSAR (Gurusamy Sarathy <[email protected]>)
    CPAN_VERSION 2.121
    CPAN_FILE    I/IL/ILYAM/Data-Dumper-2.121.tar.gz
    DSLIP_STATUS SdpOp (standard,developer,perl,object-oriented,Standard-Perl)
    MANPAGE      Data::Dumper - stringified perl data structures, suitable for b
oth printing and C
    INST_FILE    /usr/lib/perl5/5.10/i686-cygwin/Data/
    INST_VERSION 2.121_14

In the output above, CPAN tells us that we alreay have Data::Dumper version 2.121_14 installed. If you are not sure what is the exact name of a module, use the i command to fetch information using a regex:

cpan[3]> i /klingon/
Distribution    JALDHAR/DateTime-Event-Klingon-1.0.1.tar.gz
Distribution    PNE/Lingua-Klingon-Collate-1.03.tar.gz
Distribution    PNE/Lingua-Klingon-Recode-1.02.tar.gz
Distribution    PNE/Lingua-Klingon-Segment-1.03.tar.gz
Module    DateTime::Event::Klingon (JALDHAR/DateTime-Event-Klingon-1.0.1.tar.gz)

Module    Lingua::Klingon::Collate (PNE/Lingua-Klingon-Collate-1.03.tar.gz)
Module    Lingua::Klingon::Recode (PNE/Lingua-Klingon-Recode-1.02.tar.gz)
Module    Lingua::Klingon::Segment (PNE/Lingua-Klingon-Segment-1.03.tar.gz)
8 items found

Once you’re happy with the module name, you can check if it’s installed or not using m

cpan[4]> m Lingua::Klingon::Collate
Module id = Lingua::Klingon::Collate
    CPAN_USERID  PNE (Philip Newton <[email protected]>)
    CPAN_FILE    P/PN/PNE/Lingua-Klingon-Collate-1.03.tar.gz
    INST_FILE    (not installed)

Install it with install command.

cpan[5] install Lingua::Klingon::Collate

Now, unless you already have module Test::Differences installed, Lingua::Klingon::Collate will fail with a dependency error. Not all modules are like that. Some are coded in a way that CPAN actually asks you if you want to follow and install dependencies automagically. Those are a cinch to install.

If something goes wrong, look at the output of the installation. Best case scenario, you’re just missing another module and it didn’t warn you about it. For example, after Lingua::Klingon::Collate failed with the warning that I should have Test::Differences installed, I tried to install that dependency directly. It also failed. When looking at the output on the screen, I see a bunch of lines like this:

t/regression..........Can't locate Text/ in @INC (@INC contains: /home/vi
alves/.cpan/build/Test-Differences-0.4801-lI_xia/blib/lib /home/vialves/.cpan/bu
ild/Test-Differences-0.4801-lI_xia/blib/arch /usr/lib/perl5/5.10/i686-cygwin /us
r/lib/perl5/5.10 /usr/lib/perl5/site_perl/5.10/i686-cygwin /usr/lib/perl5/site_p
erl/5.10 /usr/lib/perl5/vendor_perl/5.10/i686-cygwin /usr/lib/perl5/vendor_perl/
5.10 /usr/lib/perl5/vendor_perl/5.10 /usr/lib/perl5/site_perl/5.8 /usr/lib/perl5
/vendor_perl/5.8 .) at /home/vialves/.cpan/build/Test-Differences-0.4801-lI_xia/
blib/lib/Test/ line 213.

You’ll notice that the error is the same as when we did the $ perl -Maaaa -e 'print "OK"'. Module Text/ (or namely Text::Diff) is not installed. So we now go on that quest of following dependencies by hand.

It so happens that Test::Differences tried to install Text::Diff, but Text::Diff failed during the test phase. Suppose I know that those failed tests are not important and won’t hinder the results of the rest (I don’t, but bare with me), I can force CPAN to disregard the test failures:

cpan[6]> force install Text::Diff
Running install for module 'Text::Diff'
Running make for R/RB/RBS/Text-Diff-0.35.tar.gz
  Has already been unwrapped into directory /home/vialves/.cpan/build/Text-Diff-
  Has already been made
Running make test
/usr/bin/perl.exe "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'b
lib/arch')" t/*.t
t/general.........Use of /g modifier is meaningless in split at t/general.t line
Use of /g modifier is meaningless in split at t/general.t line 130.
t/outputs.........1/8 No such file or directory at t/outputs.t line 12, 
line 6.
t/outputs......... Dubious, test returned 2 (wstat 512, 0x200)
 Failed 4/8 subtests

Test Summary Report
t/outputs.t   (Wstat: 512 Tests: 4 Failed: 0)
  Non-zero exit status: 2
  Parse errors: Bad plan.  You planned 8 tests but ran 4.
Files=6, Tests=29,  1 wallclock secs ( 0.04 usr  0.04 sys +  0.59 cusr  0.26 csy
s =  0.93 CPU)
Result: FAIL
Failed 1/6 test programs. 0/29 subtests failed.
make: *** [test_dynamic] Error 255
  /usr/bin/make test -- NOT OK
//hint// to see the cpan-testers results for installing this module, try:
  reports RBS/Text-Diff-0.35.tar.gz
Running make install
Installing /usr/lib/perl5/site_perl/5.10/Text/
Installing /usr/lib/perl5/site_perl/5.10/Text/Diff/
Writing /usr/lib/perl5/site_perl/5.10/i686-cygwin/auto/Text/Diff/.packlist
Appending installation info to /usr/lib/perl5/5.10/i686-cygwin/perllocal.pod
  /usr/bin/make install  -- OK
Failed during this command:
 RBS/Text-Diff-0.35.tar.gz                    : make_test FAILED but failure ign
ored because 'force' in effect

Now I can go on to installing Text::Differences and finally Lingua::Klingon::Collate.

cpan[7] install Test::Differences
.... some output here ....
Appending installation info to /usr/lib/perl5/5.10/i686-cygwin/perllocal.pod
  /usr/bin/make install  -- OK

cpan[8] install Lingua::Klingon::Collate
Running install for module 'Lingua::Klingon::Collate'
Running Build for P/PN/PNE/Lingua-Klingon-Collate-1.03.tar.gz
  Has already been unwrapped into directory /home/vialves/.cpan/build/Lingua-Kli
  -- No Build created, won't make
Running Build test
  Make had some problems, won't test
Running Build install
  Make had some problems, won't install

Ok, that happens. It’s because of the previous bad attempt. We can bypass that by telling CPAN to restart the build from scratch. To do so, it must first clean the build environment for that module.

cpan[9] clean Lingua::Klingon::Collate

That usually does the trick and enables you to run the install again, but if it doesn’t, you can force get Lingua::Klingon::Collate to get a fresh package.

cpan[27]> install Lingua::Klingon::Collate
Running install for module 'Lingua::Klingon::Collate'
Running Build for P/PN/PNE/Lingua-Klingon-Collate-1.03.tar.gz
  Has already been unwrapped into directory /home/vialves/.cpan/build/Lingua-Kli
ngon-Collate-1.03-ZA4a1s Going to build P/PN/PNE/Lingua-Klingon-Collate-1.03.tar.gz

Checking whether your kit is complete...
Looks good

Checking prerequisites...
Looks good

Creating new 'Build' script for 'Lingua-Klingon-Collate' version '1.03'
Copying lib/Lingua/Klingon/ -> blib/lib/Lingua/Klingon/
Manifying blib/lib/Lingua/Klingon/ -> blib/libdoc/Lingua.Klingon.Colla
HTMLifying blib/lib/Lingua/Klingon/ -> blib/libhtml/site/lib/Lingua/Kl
./Build: blib/lib/Lingua/Klingon/ cannot resolve L<strcoll(3)> in par
agraph 60.
./Build: blib/lib/Lingua/Klingon/ cannot resolve L<strxfrm(3)> in par
agraph 60.
  ./Build -- OK
Running Build test
All tests successful.
Files=5, Tests=87,  1 wallclock secs ( 0.05 usr  0.03 sys +  0.52 cusr  0.25 csy
s =  0.85 CPU)
Result: PASS
  ./Build test -- OK
Running Build install
Prepending /home/vialves/.cpan/build/Lingua-Klingon-Collate-1.03-ZA4a1s/blib/arc
h /home/vialves/.cpan/build/Lingua-Klingon-Collate-1.03-ZA4a1s/blib/lib to PERL5
LIB for 'install'
Installing /usr/lib/perl5/site_perl/5.10/Lingua/Klingon/
Installing /usr/share/man/man3/Lingua.Klingon.Collate.3pm
Installing /usr/share/doc/perl-5.10.0/html/html3/site/lib/Lingua/Klingon/Collate
Writing /usr/lib/perl5/site_perl/5.10/i686-cygwin/auto/Lingua/Klingon/Collate/.p
  ./Build install  -- OK

Type q to exit the shell and that’s it! There are many other options when using CPAN, but what you’ve seen so far in this post should be enough to get you started. Just remember to use ? every now and then to see what powers are offered to you.

More To Explore

Wordpress plugins in australia

bbPress Notify (No-Spam) Documentation

bbPress Notify (No-Spam) Documentation The bbPress Notify (No-Spam) is a free plugin that lets you control who gets notifications of new Topics and Replies in

11 Responses

  1. Hi, I have a question regarding this piece of text
    “Start up the CPAN application by calling
    $ perl -MCPAN -e shell
    If it’s the very first time you call it, you will be promped to answer a series of questions. Sticking to the default values is almost always OK. One of the first questions you will be asked is if you want CPAN to configure everything automatically. I recommend against it unless you know that the defaults are correct and will enable you to successfully install modules. ”

    You say that you don’t advice to say “yes” to the “Would you like me to configure as much as possible automatically? [yes] ” unless you are sure this would be the right configuration, and if you so, then you probably don’t need this post. But what about those like me who doesn’t know if the defaults are correct but have no idea about what to choose in case of manual configuration. In other words? What do I have to do? say [yes] and do it automatically or say [no] and then, what to say in the following steps? Thank you so much!

    1. Hi Cas,

      I recommend against answering “yes” to the “… automatically” CPAN question because people should really know what it is that they’re doing. If you say “No” to that one, it’ll start asking a bunch of questions – each one having a default answer. You should read them and see if they make sense to you. If they don’t, then the default should be OK. One of the questions is which repository to use. It’s a personal question, but I tend to a) choose my own continent due to connectivity speeds; b) choose an HTTP server (also due to speed). Feel free to post a comment regarding a particular question and I will address it.


  2. OK…I think it worked. Now I’m in “cpan[1]>” ready to follow your post. But, I have another question.. During this settings, there was a step in which CPAN module searches for external programs to work properly (bzip2, etc). I had some problems with some of them (I just copied the “missing” ones)

    Warning: make not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
    ALERT: ‘make’ is an essential tool for building perl Modules. Please make sure you have ‘make’ (or some equivalent) working.

    Warning: lynx not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Where is your lynx program? []
    Warning: wget not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Where is your wget program? []
    Warning: ncftpget not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Where is your ncftpget program? []
    Warning: ncftp not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Warning: gpg not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Where is your gpg program? []
    Warning: applypatch not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]

    Where is your applypatch program? []

    When I found this, I just pressed ENTER because by using “locate make”, for ex. I couldn’t find it (I got maaaany outputs but none looking like usr/bin/make or so). I have used this “make” command (make, make install, etc) for an exercise of a unix tutorial, so, i guess “it is” but I don’t know if CPAN module is able to work properly if I have skipped this steps. Do you know anything about it? Can this result (/usr/share/zsh/4.3.11/functions/_make) by chance, be the one CPAN is looking? (no idea..but it’s one of the outputs of locate make that looks more simple).
    : /
    Thank you Vinny.

  3. Cas,

    make is paramount in order to get most Perl modules correctly build and installed. Try running ‘which make’ (which will probably, and unfortunately, not return your make program if CPAN couldn’t find it). Which *nix are you using?

  4. Ok, I’ve discovered that “basic” Mac OSX do not have this prog’s as ‘make’, that you first need to install the “Xcode” for developers. That’s why. So.. I will first install this and then I guess there must be a way to “re-set” CPAN, this time, it should find all the programs it needs.
    *And I recall that I did that unix exercise in the other laptop, not in this one. Everything makes sense : /
    Do you think that once installed Xcode, “reload cpan” is the option to re-set configuration?
    Thank you for your time, Vinny

  5. Hi Cas,

    Indeed you need to install Xcode in the Mac. Great choice of system, btw – I’m addicted to mine.

    In order to restart CPAN from scratch, all you have to do is delete the .cpan directory from your home directory.


  6. Hi Vinny,
    ok CPAN configuration when seemly ok. And what I wanted to do afterwards, was installing Bioperl module. I did it, but I think it didn’t worked. I’ve heard that it’s common to get some message errors, and that after this you can force the installation, but I’m not sure if my errors are “afordable” or not. Can I show you my output shell? Maybe I can send you simply the file instead of copying it here (amazing saturday plan! but I’m stuck in this… : /

    Thank you, Vinny!

    1. Hi Cas,

      Sorry for the late reply – I was away on vacation for a week. Feel free to post your output here or email it to me at vinny [at] usestrict [dot] net and I’ll have a look at it. Unfortunately, it might take a while since I never installed Bioperl before and I start work on Monday and have lots to catch up.


  7. Hi Vinny, thank you so much for your help.

    I could finaly install it with out errors. Now, once installed I’m going to try couple of examples of scripts using them to see how they look like.

    But thank you so much for your help again! ; )

    Have a good time! And let’s probably talk again.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.