0N/Aperlmodinstall - Installing CPAN Modules
0N/AYou can think of a module as the fundamental unit of reusable Perl
0N/Acode; see L<perlmod> for details. Whenever anyone creates a chunk of
0N/APerl code that they think will be useful to the world, they register
0N/Aso that they can then upload their code to the CPAN. The CPAN is the
0N/AComprehensive Perl Archive Network and can be accessed at
0N/AThis documentation is for people who want to download CPAN modules
0N/Aand install them on their own computer.
2362N/AFirst, are you sure that the module isn't already on your system? Try
2362N/AC<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
0N/Ainstance, C<perl -MCGI::Carp -e 1>.
0N/AIf you don't see an error message, you have the module. (If you do
0N/Asee an error message, it's still possible you have the module, but
0N/Athat it's not in your path, which you can display with C<perl -e
0N/A"print qq(@INC)">.) For the remainder of this document, we'll assume
0N/Athat you really honestly truly lack an installed module, but have
0N/Afound it on the CPAN.
0N/ASo now you have a file ending in
.tar.gz (or, less often, .zip). You
0N/Aknow there's a tasty module inside. There are four steps you must now
0N/A=item B<DECOMPRESS> the file
0N/A=item B<UNPACK> the file into a directory
0N/A=item B<BUILD> the module (sometimes unnecessary)
0N/A=item B<INSTALL> the module.
0N/AHere's how to perform each step for each operating system. This is
0N/A<not> a substitute for reading the README and INSTALL files that
0N/Amight have come with your module!
0N/AAlso note that these instructions are tailored for installing the
0N/Amodule into your system's repository of Perl modules -- but you can
0N/Ainstall modules into any directory you wish. For instance, where I
0N/Adirectories you see when you type C<perl -e "print qq(@INC)">, you'll
0N/Awant to install them into a local directory (such as your home
0N/Adirectory) and use this approach.
0N/AB<If you're on a Unix or Linux system,>
0N/AYou can use Andreas Koenig's CPAN module
0N/Ato automate the following steps, from DECOMPRESS through INSTALL.
0N/AOr, you can combine this step with the next to save disk space:
0N/AGo into the newly-created directory and type:
0N/Ato install it locally. (Remember that if you do this, you'll have to
0N/Ais to use this module.
0N/AWhile still in that directory, type:
0N/AMake sure you have the appropriate permissions to install the module
0N/Ain your Perl 5 library directory. Often, you'll need to be root.
0N/AThat's all you need to do on Unix systems with dynamic linking.
0N/AMost Unix systems have dynamic linking -- if yours doesn't, or if for
0N/Aanother reason you have a statically-linked perl, B<and> the
0N/Amodule requires compilation, you'll need to build a new Perl binary
0N/Athat includes the module. Again, you'll probably need to be root.
0N/AB<If you're running ActivePerl (Win95/98/2K
/NT/XP, Linux, Solaris)>
0N/AFirst, type C<ppm> from a shell and see whether ActiveState's PPM
0N/Arepository has your module. If so, you can install it with C<ppm> and
0N/Ayou won't have to bother with any of the other steps here. You might
0N/Abe able to use the CPAN instructions from the "Unix or Linux" section
0N/Aabove as well; give it a try. Otherwise, you'll have to follow the
0N/Adecompress and unpack modules.
0N/AIf you used WinZip, this was already done for you.
0N/AYou'll need the C<nmake> utility, available at
0N/Aor dmake, available on CPAN.
0N/ADoes the module require compilation (
i.e. does it have files that end
0N/Ain .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
0N/Aofficially tough for you, because you have to compile the module
0N/Ayourself -- no easy feat on Windows. You'll need a compiler such as
0N/AVisual C++. Alternatively, you can download a pre-built PPM package
0N/AGo into the newly-created directory and type:
0N/AWhile still in that directory, type:
0N/AB<If you're using a Macintosh,>
0N/AFirst, make sure you have the latest B<cpan-mac> distribution (
0N/Adoing all of the steps. Read the cpan-mac directions carefully and
0N/Ainstall it. If you choose not to use cpan-mac for some reason, there
0N/Aare alternatives listed here.
0N/AAfter installing cpan-mac, drop the module archive on the
0N/AB<untarzipme> droplet, which will decompress and unpack for you.
0N/AB<Or>, you can either use the shareware B<StuffIt Expander> program
0N/Ain combination with B<DropStuff with Expander Enhancer>
0N/Aor the freeware B<MacGzip> program (
0N/AIf you're using untarzipme or StuffIt, the archive should be extracted
0N/Anow. B<Or>, you can use the freeware B<suntar> or I<Tar> (
0N/ACheck the contents of the distribution.
0N/ARead the module's documentation, looking for
0N/Areasons why you might have trouble using it with MacPerl. Look for
0N/AF<.xs> and F<.c> files, which normally denote that the distribution
0N/Amust be compiled, and you cannot install it "out of the box."
0N/A(See L<"PORTABILITY">.)
0N/AIf a module does not work on MacPerl but should, or needs to be
0N/Acompiled, see if the module exists already as a port on the
0N/AFor more information on doing XS with MacPerl yourself, see
0N/Aand then consider uploading your binary to the CPAN and
0N/Aregistering it on the MMP site.
0N/AIf you are using cpan-mac, just drop the folder on the
0N/AB<installme> droplet, and use the module.
0N/AB<Or>, if you aren't using cpan-mac, do some manual labor.
0N/AMake sure the newlines for the modules are in Mac format, not Unix format.
0N/AIf they are not then you might have decompressed them incorrectly. Check
0N/Ayour decompression and unpacking utilities settings to make sure they are
0N/Atranslating text files properly.
0N/AAs a last resort, you can use the perl one-liner:
0N/A perl
-i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
Then move the files (probably just the F<.pm> files, though there
may be some additional ones, too; check the module documentation)
to their final destination: This will
most likely be in C<$ENV{MACPERL}site_lib:> (
i.e.,
C<HD:MacPerl folder:site_lib:>). You can add new paths to
the default C<@INC> in the Preferences menu item in the
MacPerl application (C<$ENV{MACPERL}site_lib:> is added
automagically). Create whatever directory structures are required
(
i.e., for C<Some::Module>, create
C<$ENV{MACPERL}site_lib:Some:> and put
Then run the following script (or something like it):
my $dir = "${MACPERL}site_perl";
autosplit("$dir:Some:
Module.pm", "$dir:auto", 0, 1, 1);
B<If you're on the DJGPP port of DOS,>
will both uncompress and unpack.
Go into the newly-created directory and type:
You will need the packages mentioned in F<
README.dos>
in the Perl distribution.
While still in that directory, type:
You will need the packages mentioned in F<
README.dos> in the Perl distribution.
Get the EMX development suite and
gzip/tar, from either Hobbes (
the instructions for Unix.
When downloading from CPAN, save your file with a C<.tgz>
extension instead of C<
.tar.gz>. All other periods in the
filename should be replaced with underscores. For example,
or, for zipped modules, type
Executables for gzip, zip, and VMStar:
package. The former is a simple compression tool; the latter permits
creation of multi-file archives.
Or, if you're fond of VMS command syntax:
Make sure you have MMS (from Digital) or the freeware MMK ( available
Now you're ready to build:
Substitute C<mmk> for C<mms> above if you're using MMK.
Substitute C<mmk> for C<mms> above if you're using MMK.
Introduce the F<
.tar.gz> file into an HFS as binary; don't translate from
The BUILD and INSTALL steps are identical to those for Unix. Some
modules generate Makefiles that work better with GNU make, which is
Note that not all modules will work with on all platforms.
See L<perlport> for more information on portability issues.
Read the documentation to see if the module will work on your
system. There are basically three categories
of modules that will not work "out of the box" with all
platforms (with some possibility of overlap):
B<Those that should, but don't.> These need to be fixed; consider
contacting the author and possibly writing a patch.
B<Those that need to be compiled, where the target platform
doesn't have compilers readily available.> (These modules contain
F<.xs> or F<.c> files, usually.) You might be able to find
existing binaries on the CPAN or elsewhere, or you might
want to try getting compilers and building it yourself, and then
release the binary for other poor souls to use.
B<Those that are targeted at a specific platform.>
(Such as the Win32:: modules.) If the module is targeted
specifically at a platform other than yours, you're out
Check the CPAN Testers if a module should work with your platform
but it doesn't behave as you'd expect, or you aren't sure whether or
not a module will work under your platform. If the module you want
isn't listed there, you can test it yourself and let CPAN Testers know,
you can join CPAN Testers, or you can request it be tested.
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 acknowledge all your questions. Contact the module
familiar with Perl on your operating system.
with invaluable help from Chris Nandor, and valuable help from Brandon
Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
First version July 22, 1998; last revised November 21, 2001.
Copyright (C) 1998, 2002, 2003 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
Permission is granted to copy and distribute modified versions of this
documentation under the conditions for verbatim copying, provided also
that they are marked clearly as modified versions, that the authors'
names and title are unchanged (though subtitles and additional
authors' names may be added), and that the entire resulting derived
work is distributed under the terms of a permission notice identical
Permission is granted to copy and distribute translations of this
documentation into another language, under the above conditions for