perltutorial
tachyon
<p>This is a brief guide to installing modules. For some background on what a
module is and where they live on the system see the [Simple Module Tutorial]</p>
<p><a href="#basics">The Basics of Module Installation</a></p>
<p><a href="#fix">Fixing common problems</a></p>
<ul>
<li><a href="#depend">When I perl Makefile.PL I get a Warning: prerequisite Foo::Bar failed to load: Can't locate
foo/bar.pm in @INC....</a></li>
<li><a href="#nomake">I get an error saying &quot;Can't find make&quot;</a></li>
<li><a href="#missing">make/nmake reports missing files</a></li>
<li><a href="#test">make test reports errors</a></li>
<li><a href="#permission">I don't have permission to install a module on the system!</a></li>
</ul>
<p><a href="#tools">Tools to make the job easier CPAN and PPM</a></p>
<ul>
<li><a href="#cpan">CPAN.pm</a></li>
<li><a href="#ppm">PPM</a></li>
</ul>
<p><a href="#c">Installing
Modules that include elements coded in C</a></p>
<h2><a name="basics"></a>The Basics of Module Installation</h2>
<p>Most modules are available from CPAN - the <a href="http://www.perl.com/CPAN/">Comprehensive
Perl Archive Network</a>. They are supplied in what is known as a tarball. A
tarball is a gzip compressed tar file. When a module is made the directory structure
it lives in is converted to a single file that contains both the files and the
directory information. A program called tar performs this function and the
resultant file is called a tar file. Tar files have a .tar file extension. This
tar file is then compressed using the gzip (GNU Zip) program. Gzipped files have
a .gz extension thus a standard module will be called something like:</p>
<pre>Some-Module-0.01.tar.gz</pre>
<p>The first part is the name, the next part the version number and the last
part the .tar.gz extension signifying that this is a tarball. You uncompress a
tarball using the tar program like this (the $ represents the command prompt):</p>
<pre>$ tar -zxvf Some-Module-0.01.tar.gz</pre>
<p>All *nix systems will have a tar program. On windows you can use <a href="http://sources.redhat.com/cygwin/">CYGWIN</a>
which is a set of UNIX tools ported to Win32 to get tar but programs like <a href="http://www.winzip.com/">WinZip</a>
will handle extracting tarballs just fine.</p> One issue with Winzip is that it does not deal well with .tar.tar as an extension. Fix it by changing the extension to tar.gz.
<p>Once your have extracted your tarball you then need to make and install your
files. You do that like this. At the command prompt navigate your way to the
directory created where you extracted the tarball.&nbsp; Making your extractions
in a /temp dir is a good idea in case of problems with badly made distributions.
There may be several
directories to move through. In our hypothetical example above we would expect
the tarball to extract into a directory called &quot;Some-Module-0.01&quot;,
however it may extract to &quot;Some&quot; or even straight into the current
working directory (this is not fun to clean up, thus the suggestion of using a
/temp dir). Within this module directory we
should find a file called &quot;Makefile.PL&quot; although it *may* be several
dirs deep. Once you find the Makefile.PL you do the
following:</p>
<pre>$ perl Makefile.PL
$ make
$ make test
$ make install</pre>
<p>This should all proceed smoothly and your module should be installed, if not
see below. Note on Win32 you will need to use a program called nmake. You can
get a copy from M$ here: <a href="ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe">nmake
via FTP</a> or here <a href="http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe">nmake
via HTTP</a> Once you have downloaded it you need to run the program (it self
extracts) and make sure that you do this in a directory that is on your PATH.
The PATH is a list of directories that Win32 will search for executable files.
When you type nmake you want Windows to be able to find the program so it must
be in one of the directories on the PATH. To see your current PATH type PATH at
the command prompt. [C:\WINDOWS] or [C:\WINNT] will be a fairly safe
bet.
<p>Now that you have got nmake and extracted it in a directory on your PATH you
just do this:</p>
<pre>C:\&gt; perl Makefile.PL
C:\&gt; nmake
C:\&gt; nmake test
C:\&gt; nmake install
</pre>
<p>Ok either everything went fine or you got some errors. Note in the following
read nmake for make if your are on Win32</p>
<h2><a name="fix"></a>Fixing common problems</h2>
<h3><a name="depend"></a>When I perl Makefile.PL or make test I get a Warning: prerequisite Foo::Bar failed to load: Can't locate foo/bar.pm in @INC....</h3>
<p>Some modules have dependencies. They depend on other modules to function.
These are specified in the Makefile.PL in the line:</p>
<pre>'PREREQ_PM' =&gt; { Foo::Bar =&gt; 1.5 }</pre>
<p>This line specifies that the module you are trying to install require a
module called Foo:Bar and that the version of this module must be 1.5 or
greater. If you get these type of errors you will need to download and install
these module(s) first. You should find details in the README file - did you
READIT?
</p>
<p>Some Authors forget to edit their Makefile.PL with dependencies - in this
case you will generally get this error message when you run the tests as the new
module tries to load non-existent modules on which it is dependent.<br>
</p>
<h3 align="left"><a name="nomake"></a>I get an error saying &quot;Can't find make&quot;</h3>
<p>As noted before when you say make/nmake the operating system looks along the
path for an executable by the right name. If it can't find one you get this
error. To fix it simple modify your path or specify the full path to the
executable such as:</p>
<pre>$ ~/make</pre>
<p>This tells the operating system to use the make executable in your home
directory where you just put it OK
<h3><a name="missing"></a>make/nmake reports missing files</h3>
<p>When you run make/nmake it looks for a file called MANIFEST which lists all
the files that should be present in the distribution. If some are missing you
get an error like:<pre>$ make
Checking if your kit is complete...
Warning: the following files are missing in your kit:
Foo.bar
Please inform the author.
$</pre>
<p>This is slack on the authors part for producing a
broken distribution. Get a good one!<h3><a name="test"></a>make test reports errors</h3>
<p>While modules should be portable across operating systems some are not. To
ensure that a module is working correctly most authors develop a test suite of
programs that ensure the module is behaving as expected. When you run:<pre>$ make test</pre>
<p>These scripts are all run. Some errors are trivial but some are
significant. If you get errors consult the README and look at the results to see
what is broken. The author will want to know about these and may be able to help
fix them.<p>If you get a lot of errors it is probably wise not to make install
and install the module.<h3><a name="permission"></a>I don't have permission to install a module on the system!</h3>
<p>If you don't have root permission you will not be able to install a module in
the usual place on a shared user system. If you do not have root access you may
get errors like:</p>
<pre>$ make install
Warning: You do not have permissions to install into
/usr/local/lib/perl5/site_perl/5.005/i386-freebsd at
/usr/libdata/perl/5.00503/ExtUtils/Install.pm line 62.
mkdir /usr/local/lib/perl5/site_perl/5.005/CGI/Simple:
Permission denied at /usr/libdata/perl/5.00503/ExtUtils/Install.pm line 120
*** Error code 2</pre>
<p>&nbsp;This is easy to get around. You just
install it locally in your home directory. Make a directory called say /lib in
your home directory like this:</p>
<pre># first navigate to your home directory
$ cd ~</pre>
<pre># now make a directory called lib
# on UNIX
$ mkdir lib
# on Win32
C:\&gt; md lib</pre>
<p>Now you have a directory called ~/lib where the ~ represents the path to your
home dir. ~ literally means your home dir but you knew that already. All you need to do is add a modifier to your perl Makefile.PL command</p>
<pre>$ perl Makefile.PL PREFIX=~/lib LIB=~/lib</pre>
<p>This tell MakeMaker to install the files in the lib directory in your home
directory. You then just make/nmake as before. To use the module you just need
to add ~/lib to @INC. See [Simple Module Tutorial]
for full details of how. In a nutshell the top of your scripts will look like this:
<pre>
#!/usr/bin/perl -w
use strict;
# add your ~/lib dir to @INC
use lib '/usr/home/your_home_dir/lib/';
# proceed as usual
use Some::Module;
</pre>
</p>
<h2><a name="tools"></a>Tools to make the job easier CPAN and PPM</h2>
<p>There are some tools to make installing modules even easier. They may be
difficult to get working through firewalls or proxies. Read the docs for
configuration hints.<h3><a name="cpan"></a>CPAN.pm</h3>
<p>CPAN.pm is a perl module that installs perl modules! It is part of the
standard distribution so you should have a copy available. The easiest way to use
it is like this (note the use of different quotes on different OSs):<pre># Win32
C:\&gt; perl -MCPAN -e &quot;shell&quot;</pre>
<pre># UNIX
$ perl -MCPAN -e 'shell'</pre>
<p>This fires up the interactive shell. Follow the
prompts and accept the defaults.<h3><a name="ppm"></a>PPM</h3>
<p>PPM is the Perl Package Manager from <a href="http://www.activestate.com">ActiveState</a>. See [A guide to installing modules for Win32] for full details. It installs special
versions of CPAN modules wrapped in an XML format called a PPD file. To file up
the shell:<pre>C:\&gt;PPM
PPM&gt;</pre>
<p>Type help at the prompt for commands and see the docs. If you
can't get PPM to work through your proxy/firewall then download the .zip files
of the PPD files from <a href="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/Zips">here</a>, unzip them, navigate to the directory you unzipped them into
and then run:<pre>C:\&gt;PPM install Some-Module.ppd</pre>
<h2><a name="c"></a>Installing
Modules that include elements coded in C</h2>
<p>The most difficult modules to install are generally those that include parts
of the module written in C. These modules require that you have a *good* C
compiler on your system - generally gcc is best. On most UNIX systems you will
have a C compiler but on Win32 you will probably not have as it is not a part of
Windows. If you do not have a C compiler you will need to install one. Get a
copy of gcc direct from the source here:<p><a href="http://www.gnu.org/software/gcc/gcc.html">http://www.gnu.org/software/gcc/gcc.html</a>
<p>Getting modules compiling on Win32 can be tricky. See [A Practical Guide to Compiling C based Modules under ActiveState using Microsoft C++]. Just getting cygwin/MinGW and gcc is not enough. The easiset solution is to try to find a precompiled binary version (try ActiveState
for a PPM or the Author) or email the Author the tale of your woes. If you are
using Win32 expect the author to suggest you get a real OS but.....<p>cheers<p>tachyon<br>
<p>Corrected a few technical inexactitudes (similar to issues ;-) thanks to [Hanamaki]