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