perlmodinstall - Installing CPAN Modules
DESCRIPTION
You can think of a module as the fundamental unit of
reusable Perl code; See the perlmod manpage for details.
Whenever anyone creates a chunk of Perl code that they
think will be useful to the world, they register as a Perl
developer at http://www.perl.com/CPAN/modules/04pause.html
so that they can then upload their code to CPAN. CPAN is
the Comprehensive Perl Archive Network and can be accessed
at http://www.perl.com/CPAN/, or searched via
http://cpan.perl.com/ and http://theory.uwin
nipeg.ca/mod_perl/cpan-search.pl .
This documentation is for people who want to download CPAN
modules and install them on their own computer.
PREAMBLE
You have a file ending in .tar.gz (or, less often, .zip).
You know there's a tasty module inside. You must now take
four steps:
DECOMPRESS the file
UNPACK the file into a directory
BUILD the module (sometimes unnecessary)
INSTALL the module.
Here's how to perform each step for each operating system.
This is not a substitute for reading the README and
INSTALL files that might have come with your module!
Also note that these instructions are tailored for
installing the module into your system's repository of
Perl modules. But you can install modules into any direc
tory you wish. For instance, where I say `perl Make
file.PL', you can substitute `perl Makefile.PL PRE
FIX=/my/perl_directory' to install the modules into
`/my/perl_directory'. Then you can use the modules from
your Perl programs with `use lib "/my/perl_direc
tory/lib/site_perl"' or sometimes just `use
"/my/perl_directory"'.
· If you're on Unix,
You can use Andreas Koenig's CPAN module (which comes
standard with Perl, or can itself be downloaded from
http://www.perl.com/CPAN/modules/by-module/CPAN) to
automate the following steps, from DECOMPRESS through
INSTALL.
Decompress the file with `gzip -d yourmodule.tar.gz'
You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
Or, you can combine this step with the next to save
disk space:
gzip -dc yourmodule.tar.gz | tar -xof -
B. UNPACK
Unpack the result with `tar -xof yourmodule.tar'
C. BUILD
Go into the newly-created directory and type:
perl Makefile.PL
make
make test
D. INSTALL
While still in that directory, type:
make install
Make sure you have appropriate permissions to install
the module in your Perl 5 library directory. Often,
you'll need to be root.
Perl maintains a record of all module installations.
To look at this list, simply type:
perldoc perllocal
That's all you need to do on Unix systems with dynamic
linking. Most Unix systems have dynamic linking--if
yours doesn't, or if for another reason you have a
statically-linked perl, and the module requires compi
lation, you'll need to build a new Perl binary that
includes the module. Again, you'll probably need to
be root.
· If you're running Windows 95 or NT with the ActiveS
tate port of Perl
A. DECOMPRESS
You can use the shareware Winzip program (
http://www.winzip.com ) to decompress and unpack mod
ules.
If you used WinZip, this was already done for you.
C. BUILD
Does the module require compilation (i.e. does it have
files that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?
If it does, you're on your own. You can try compiling
it yourself if you have a C compiler. If you're suc
cessful, consider uploading the resulting binary to
CPAN for others to use. If it doesn't, go to INSTALL.
D. INSTALL
Copy the module into your Perl's lib directory.
That'll be one of the directories you see when you
type
perl -e 'print "@INC"'
· If you're running Windows 95 or NT with the core Win
dows distribution of Perl,
A. DECOMPRESS
When you download the module, make sure it ends in
either .tar.gz or .zip. Windows browsers sometimes
download `.tar.gz' files as `_tar.tar', because early
versions of Windows prohibited more than one dot in a
filename.
You can use the shareware WinZip program (
http://www.winzip.com ) to decompress and unpack mod
ules.
Or, you can use InfoZip's `unzip' utility (
http://www.cdrom.com/pub/infozip/ ) to uncompress
`.zip' files; type `unzip yourmodule.zip' in your
shell.
Or, if you have a working `tar' and `gzip', you can
type
gzip -cd yourmodule.tar.gz | tar xvf -
in the shell to decompress `yourmodule.tar.gz'. This
will UNPACK your module as well.
B. UNPACK
The methods in DECOMPRESS will have done this for you.
Go into the newly-created directory and type:
perl Makefile.PL
dmake
dmake test
Depending on your perl configuration, `dmake' might
not be available. You might have to substitute what
ever `perl -V:make' says. (Usually, that will be
`nmake' or `make'.)
D. INSTALL
While still in that directory, type:
dmake install
· If you're using a Macintosh,
A. DECOMPRESS
In general, all Macintosh decompression utilities men
tioned here can be found in the Info-Mac Hyperarchive
( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
Specificly the "Commpress & Translate" listing (
http://hyperarchive.lcs.mit.edu/HyperAr
chive/Abstracts/cmp/HyperArchive.html ).
You can either use the shareware StuffIt Expander pro
gram ( http://www.aladdinsys.com/expander/ ) in combi
nation with DropStuff with Expander Enhancer (
http://www.aladdinsys.com/dropstuff/ ) or the freeware
MacGzip program ( http://persephone.cps.unizar.es/gen
eral/gente/spd/gzip/gzip.html ).
B. UNPACK
If you're using DropStuff or Stuffit, you can just
extract the tar archive. Otherwise, you can use the
freeware suntar or Tar ( http://hyperar
chive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
C. BUILD
Does the module require compilation?
1. If it does,
Overview: You need MPW and a combination of new and
old CodeWarrior compilers for MPW and libraries.
Makefiles created for building under MPW use
build without other compilers, but it has not been
done successfully, to our knowledge. Read the docu
mentation in MacPerl: Power and Ease (
http://www.ptf.com/macperl/ ) on porting/building
extensions, or find an existing precompiled binary, or
hire someone to build it for you.
Or, ask someone on the mac-perl mailing list (mac-
perl@iis.ee.ethz.ch) to build it for you. To sub
scribe to the mac-perl mailing list, send mail to mac-
perl-request@iis.ee.ethz.ch.
2. If the module doesn't require compilation, go to
INSTALL.
D. INSTALL
Make sure the newlines for the modules are in Mac for
mat, not Unix format. If they are not then you might
have decompressed them incorrectly. Check your decom
pression and unpacking utilities settings to make sure
they are translating text files properly.
As a last resort, you can use the perl one-liner:
perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
on the source files.
Move the files manually into the correct folders.
Move the files to their final destination: This will
most likely be in `$ENV{MACPERL}site_lib:' (i.e.,
`HD:MacPerl folder:site_lib:'). You can add new paths
to the default `@INC' in the Preferences menu item in
the MacPerl application (`$ENV{MACPERL}site_lib:' is
added automagically). Create whatever directory
structures are required (i.e., for `Some::Module',
create `$ENV{MACPERL}site_lib:Some:' and put `Mod
ule.pm' in that directory).
Run the following script (or something like it):
#!perl -w
use AutoSplit;
my $dir = "${MACPERL}site_perl";
autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
Eventually there should be a way to automate the
installation process; some solutions exist, but none
are ready for the general public yet.
A. DECOMPRESS
djtarx ( ftp://ftp.simtel.net/pub/simtel
net/gnu/djgpp/v2/ ) will both uncompress and unpack.
B. UNPACK
See above.
C. BUILD
Go into the newly-created directory and type:
perl Makefile.PL
make
make test
You will need the packages mentioned in README.dos in
the Perl distribution.
D. INSTALL
While still in that directory, type:
make install
You will need the packages mentioned in README.dos in
the Perl distribution.
· If you're on OS/2,
Get the EMX development suite and gzip/tar, from
either Hobbes ( http://hobbes.nmsu.edu ) or Leo (
http://www.leo.org ), and then follow the instructions
for Unix.
· If you're on VMS,
When downloading from CPAN, save your file with a .tgz
extension instead of .tar.gz. All other periods in
the filename should be replaced with underscores. For
example, `Your-Module-1.33.tar.gz' should be down
loaded as `Your-Module-1_33.tgz'.
A. DECOMPRESS
Type
gzip -d Your-Module.tgz
or, for zipped modules, type
Executables for gzip, zip, and VMStar ( Alphas:
http://www.openvms.digital.com/free
ware/000TOOLS/ALPHA/ and Vaxen: http://www.open
vms.digital.com/freeware/000TOOLS/VAX/ ).
gzip and tar are also available at ftp://ftp.digi
tal.com/pub/VMS.
Note that GNU's gzip/gunzip is not the same as Info-
ZIP's zip/unzip package. The former is a simple com
pression tool; the latter permits creation of multi-
file archives.
B. UNPACK
If you're using VMStar:
VMStar xf Your-Module.tar
Or, if you're fond of VMS command syntax:
tar/extract/verbose Your_Module.tar
C. BUILD
Make sure you have MMS (from Digital) or the freeware
MMK ( available from MadGoat at http://www.mad
goat.com ). Then type this to create the DESCRIP.MMS
for the module:
perl Makefile.PL
Now you're ready to build:
mms
mms test
Substitute `mmk' for `mms' above if you're using MMK.
D. INSTALL
Type
mms install
Substitute `mmk' for `mms' above if you're using MMK.
· If you're on MVS,
Introduce the .tar.gz file into an HFS as binary;
don't translate from ASCII to EBCDIC.
Decompress the file with C<gzip -d yourmodule.tar.gz>
You can get gzip from
http://www.s390.ibm.com/products/oe/bpxqp1.html.
B. UNPACK
Unpack the result with
pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
The BUILD and INSTALL steps are identical to those for
Unix. Some modules generate Makefiles that work bet
ter with GNU make, which is available from
http://www.mks.com/s390/gnu/index.htm.
HEY
If you have any suggested changes for this page, let me
know. Please don't send me mail asking for help on how to
install your modules. There are too many modules, and too
few Orwants, for me to be able to answer or even acknowl
edge all your questions. Contact the module author
instead, or post to comp.lang.perl.modules, or ask someone
familiar with Perl on your operating system.
AUTHOR
Jon Orwant
orwant@tpj.com
The Perl Journal, http://tpj.com
with invaluable help from Brandon Allbery, Charles Bailey,
Graham Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holz
man, Tom Horsley, Nick Ing-Simmons, Tuomas J. Lukka, Las
zlo Molnar, Chris Nandor, Alan Olsen, Peter Prymmer,
Gurusamy Sarathy, Christoph Spalinger, Dan Sugalski, Larry
Virden, and Ilya Zakharevich.
July 22, 1998
COPYRIGHT
Copyright (C) 1998 Jon Orwant. All Rights Reserved.
Permission is granted to make and distribute verbatim
copies of this documentation provided the copyright notice
and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified ver
sions of this documentation under the conditions for ver
batim copying, provided also that they are marked clearly
as modified versions, that the authors' names and title
names may be added), and that the entire resulting derived
work is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations
of this documentation into another language, under the
above conditions for modified versions.
Man(1) output converted with
man2html