One of the reasons I find Perl so useful is there are many programs that that are user-freindly and the authors of these programs are willing to share them. Sometimes they appear on the web, sometimes in print, and of course, in the Comprehensive Perl Archive Network, or CPAN.One of the reasons I find Perl so useful is there are many programs that that are user-freindly and the authors of these programs are willing to share them. Sometimes they appear on the web, sometimes in print, and of course, in the Comprehensive Perl Archive Network, or CPAN. Often, the code you are interested in is either a perl module, or a script that uses a module to do the brunt of the work.

If you use Perl on a Windows machine, ActiveState’s Perl Package manager is the easiest way to download and install modules. If you use Perl on a unix machine, then your sysadmin can install Perl modules for you. But it does take their time, and they may charge you for that. Sometimes you just want to test the module, without knowing if it is even useful to you. “You can do it yourself, you know,” they may even say to you. That’s true, and this article shows you how.

The first thing we want to do is figure out where we want to store the modules. I’m going to use a fictional example. Let’s assume we run the website for www.YNOTcollege.edu but not the server where it sits. The html is stored in /usr/local/dean/public_html and the CGI scripts are below that: /usr/local/dean/public_html/cgi-bin.

Since I want to use these modules for CGI, lets put them in the cgi-bin directory. But let’s keep the modules separate from the code by making a seperate edirectory for them. We could call it anything, but I like perl5lib:

%mkdir /usr/local/dean/public_html/cgi-bin/perl5lib

The files you get from CPAN are like setup.exe programs. They’ll put things in the right place, but they aren’t the finished product. We may want to remove them when we are done. So we’ll start with the raw file in a temp directory:

%mkdir /usr/local/dean/temp

That’s really all the setup we need to do. Let’s go get a module from CPAN and finish the example.

Next I’m going to CPAN to get a module. I will use lynx, a text only browser, because it is handy in unix and lets me save files directly to my account. There is no reason why you couldn’t use a different browser, save the file to your local machine, and then FTP the file to your unix account.

Point a browser to CPAN, http://www.cpan.org/, or specifically, the modules list at http://www.cpan.org/modules/. You can browse by category, by module name, by author, or for recently added modules. The naming scheme is actually well organized thanks to the CPAN volunteers, so if you browse by name the list will be quite clear to you. Also, you’ll see just how large this collection really is!

In this example, I am going to go into the Business directory. There you can see some actual modules in addition to links to directories. The module files are in .tar.gz files (tarred and GNU-zipped). There may also be documentation in .readme files. I like to look through the .readme’s sometimes, seeing what’s ineresting, just as if I were in the middle of a bookshop. I came here looking for the CreditCard module, but Business-ISBN caught my eye, so I took a look at it and I decided to grab that at the same time.

If we examine the Business-CreditCard files, we see there is more than one file. That’s because there are sometimes older and newer versions of the module around. I’ll take the newest one, but I’ll be sure to read the documentation that comes with it, because it may be a beta release. Beta releases are usually indicated with a “b” in the version, but you should always check documentation to be sure.

As I said, I’m using lynx. When I hit return on the link to the file, lynx prompts me if I want to save the file. If you’re using a different browser, you’ll be told it is a file of an unknown type, and asked if you wish to save it. Save it and then upload it to the temp directory on your unix account.

Now let’s look at our temp directory.

% ls
>Business-CreditCard-0.21.tar.gz Business-ISBN-19990112.tar.gz
Next step is to unwrap the .tar.gz file. We can do this in one command, tar -zxvf, and we repeat it for each .tar.gz file.

% tar -zxvf Business-CreditCard-0.21.tar.gz
>Business-CreditCard-0.21
>Business-CreditCard-0.21/CreditCard.pm
% tar -zxvf Bu.siness-ISBN-19990112.tar.gz
>Business-ISBN-19990112/
>Business-ISBN-19990112/Makefile.PL
>Business-ISBN-19990112/Changes Business-ISBN-19990112/README >Business-ISBN-19990112/MANIFEST Business-ISBN-19990112/ISBN.pm

Now, looking at the output, I see that the Business-CreditCard
file consistss of only one file, CreditCard.pm. The .pm extension stands for perl module. That means we could just copy this file to our perl5lib directory and be done.

The Business-ISBN directory, on the other hand, has so much stuff it needs a MANIFEST! So we check the MANIFEST, verify that all the files arrived, and then wonder what to do next. We look at the README file and see…nothing!

Don’t panic! I’ll tell you what to do next. The next thing we need to do is run the Makefile.PL routine. Normally, this is just the command perl Makefile.PL.

That won’t work for us, however, because the Makefile.PL routine assumes that we are the sysadmin (root) and have access to the standard perl directories. In our case, we are just a simple user installing this to our own perl5lib directory. So we have to specify the directory by using the LIB (library) directive, as in the following command:

% perl ./Makefile.PL LIB=/usr/local/dean/public_html/ cgi-bin/perl5lib
>Checking if your kit is complete…
>Looks good
>Writing Makefile for Business::ISBN
% ls

This changes ISBN.pm MANIFEST Makefile Makefile.PL and README. Of course, if you are the sysadmin, go ahead and use perl Makefile.PL. The next three commands are the same either way. The commands are make, make test, and make install. Let’s look at some sample output:

% make
>mkdir blib
>mkdir blib/lib
>mkdir blib/lib/Business
>mkdir blib/arch
>mkdir blib/arch/auto
>mkdir blib/arch/auto/Business
>mkdir blib/arch/auto/Business/ISBN
>mkdir blib/lib/auto
>mkdir blib/lib/auto/Business
>mkdir blib/lib/auto/Business/ISBN
>mkdir blib/man3
>cp ISBN.pm blib/lib/Business/ISBN.pm
>Manifying blib/man3/Business::ISBN.3
>/usr/bin/pod2man: ISBN.pm is missing required section: >DESCRIPTION
% make test
>No tests defined for Business::ISBN extension.
% make install
>Warning: You do not have permissions to install >into /usr/lib/perl5/man/man3 at /usr/lib/perl5/ExtUtils/Install.pm line 61.
>Installing /usr/local/dean/public_html/cgi->bin/perllib/Business/ISBN.pm
>Installing /usr/lib/perl5/man/man3/Business::ISBN.3
>Writing /usr/local/dean/public_html/cgi-bin/perllib/i386->linux/auto/Business/ISBN/.packlist
>Appending installation info to /usr/local/dean/public_html/cgi->bin/perllib/i386-linux/perllocal.pod

That’s more like it! The ISBN module is installed and ready to use. Take a look at the perl5lib directory, and you’ll see that a new Business directory has been created there, and that the ISBN.pm file has been written inside the Business directory.

Now we can copy the CreditCard module over to the Business directory, so that when we say use Business::CreditCard; in a program, Perl can properly find CreditCard.pm in the business directory.

Since we did make our own perl library, however, we’ll have to tell Perl that in the program as well. Just as we specified the library path in the perl ./Makefile.PL step above, in our perl program, we’ll need to say use lib ‘/usr/local/dean/public_html/cgi-bin/perl5lib’; before any other use statements.

For secure cgi scripts, we may need to define the library relative to the cgi-bin directory. In this case, we would write
use lib ‘./perl5lib’; in our code before we included the module with the statement use Business::CreditCard;.

Notice that there is one error reported in our make steps. The last step, make install, had no permission to write the documentation alongside the other manpages. But that’s ok, because the modules contain their own documentation. The following command gives all kinds of information:

% perldoc /usr/local/dean/public_html/cgi-bin/perl5lib/Business/ISBN.pm

It would be nice if we could use a shorthand for this, and we can. But first we have to set an environmental variable so that the perldoc command knows where to look for the module files.

The environmental variable you want to set is PERL5LIB, and the value it should be set to is the full path to your perl5lib directory. The most common place to set this variable is in the .login file of your home directory (where you show up when you login).

You may need to use the setenv command: setenv PERL5LIB /usr/local/dean/public_html/cgi-bin/perl5lib or just define the variable directly, PERL5LIB=/usr/local/dean/public_html/cgi-bin/perl5lib. Follow the pattern of what is in the .login file, or ask your sysadmin for help. Once the PERL5LIB variable is set, we can use perldoc on modules we installed ourselves as if they were any standard module: perldoc Business::ISBN.