3 perlmodinstall - Installing CPAN Modules
7 You can think of a module as the fundamental unit of reusable Perl
8 code; See L<perlmod> for details. Whenever anyone creates a chunk
9 of Perl code that they think will be useful to the world, they
10 register as a Perl developer at
11 http://www.perl.com/CPAN/modules/04pause.html so that they can then
12 upload their code to CPAN. CPAN is the Comprehensive Perl Archive
13 Network and can be accessed at http://www.perl.com/CPAN/, or searched
14 via http://cpan.perl.com/ and
15 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
17 This documentation is for people who want to download CPAN modules
18 and install them on their own computer.
22 You have a file ending in F<.tar.gz> (or, less often, F<.zip>).
23 You know there's a tasty module inside. You must now take four
28 =item B<DECOMPRESS> the file
30 =item B<UNPACK> the file into a directory
32 =item B<BUILD> the module (sometimes unnecessary)
34 =item B<INSTALL> the module.
38 Here's how to perform each step for each operating system. This is
39 I<not> a substitute for reading the README and INSTALL files that
40 might have come with your module!
42 Also note that these instructions are tailored for installing the
43 module into your system's repository of Perl modules. But you can
44 install modules into any directory you wish. For instance, where I
45 say C<perl Makefile.PL>, you can substitute C<perl
46 Makefile.PL PREFIX=/my/perl_directory> to install the modules
47 into C</my/perl_directory>. Then you can use the modules
48 from your Perl programs with C<use lib
49 "/my/perl_directory/lib/site_perl"> or sometimes just C<use
50 "/my/perl_directory">.
58 You can use Andreas Koenig's CPAN module
59 (which comes standard with Perl, or can itself be downloaded
60 from http://www.perl.com/CPAN/modules/by-module/CPAN)
61 to automate the following steps, from DECOMPRESS through INSTALL.
65 Decompress the file with C<gzip -d yourmodule.tar.gz>
67 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
69 Or, you can combine this step with the next to save disk space:
71 gzip -dc yourmodule.tar.gz | tar -xof -
75 Unpack the result with C<tar -xof yourmodule.tar>
79 Go into the newly-created directory and type:
87 While still in that directory, type:
91 Make sure you have appropriate permissions to install the module
92 in your Perl 5 library directory. Often, you'll need to be root.
94 That's all you need to do on Unix systems with dynamic linking.
95 Most Unix systems have dynamic linking--if yours doesn't, or if for
96 another reason you have a statically-linked perl, I<and> the
97 module requires compilation, you'll need to build a new Perl binary
98 that includes the module. Again, you'll probably need to be root.
102 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
106 You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
107 decompress and unpack modules.
111 If you used WinZip, this was already done for you.
115 Does the module require compilation (i.e. does it have files
116 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on
117 your own. You can try compiling it yourself if you have a C compiler.
118 If you're successful, consider uploading the resulting binary to
119 CPAN for others to use. If it doesn't, go to INSTALL.
123 Copy the module into your Perl's I<lib> directory. That'll be one
124 of the directories you see when you type
126 perl -e 'print "@INC"'
130 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
134 When you download the module, make sure it ends in either
135 F<.tar.gz> or F<.zip>. Windows browsers sometimes
136 download C<.tar.gz> files as C<_tar.tar>, because
137 early versions of Windows prohibited more than one dot in a filename.
139 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
140 decompress and unpack modules.
142 Or, you can use InfoZip's C<unzip> utility (
143 http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
144 C<unzip yourmodule.zip> in your shell.
146 Or, if you have a working C<tar> and C<gzip>, you can
149 gzip -cd yourmodule.tar.gz | tar xvf -
151 in the shell to decompress C<yourmodule.tar.gz>. This will
152 UNPACK your module as well.
156 The methods in DECOMPRESS will have done this for you.
160 Go into the newly-created directory and type:
166 Depending on your perl configuration, C<dmake> might not be
167 available. You might have to substitute whatever C<perl
168 -V:make> says. (Usually, that will be C<nmake> or
173 While still in that directory, type:
179 B<If you're using a Macintosh,>
183 In general, all Macintosh decompression utilities mentioned here
184 can be found in the Info-Mac Hyperarchive
185 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
186 Specificly the "Commpress & Translate" listing
187 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
190 You can either use the shareware B<StuffIt Expander> program
191 ( http://www.aladdinsys.com/expander/ )
192 in combination with I<DropStuff with Expander Enhancer>
193 ( http://www.aladdinsys.com/dropstuff/ )
194 or the freeware B<MacGzip> program (
195 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
200 If you're using DropStuff or Stuffit, you can just extract the tar
201 archive. Otherwise, you can use the freeware B<suntar> or I<Tar> (
202 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
206 Does the module require compilation?
210 Overview: You need MPW and a combination of new and old CodeWarrior
211 compilers for MPW and libraries. Makefiles created for building under
212 MPW use Metrowerks compilers. It's most likely possible to build
213 without other compilers, but it has not been done successfully, to our
214 knowledge. Read the documentation in I<MacPerl: Power and Ease> (
215 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
216 an existing precompiled binary, or hire someone to build it for you.
218 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
219 to build it for you. To subscribe to the mac-perl mailing list, send
220 mail to mac-perl-request@iis.ee.ethz.ch.
222 2. If the module doesn't require compilation, go to INSTALL.
226 Make sure the newlines for the modules are in Mac format, not Unix format.
227 If they are not then you might have decompressed them incorrectly. Check
228 your decompression and unpacking utilities settings to make sure they are
229 translating text files properly.
231 As a last resort, you can use the perl one-liner:
233 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
237 Move the files manually into the correct folders.
239 Move the files to their final destination: This will
240 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
241 C<HD:MacPerl folder:site_lib:>). You can add new paths to
242 the default C<@INC> in the Preferences menu item in the
243 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
244 automagically). Create whatever directory structures are required
245 (i.e., for C<Some::Module>, create
246 C<$ENV{MACPERL}site_lib:Some:> and put
247 C<Module.pm> in that directory).
249 Run the following script (or something like it):
253 my $dir = "${MACPERL}site_perl";
254 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
256 Eventually there should be a way to automate the installation process; some
257 solutions exist, but none are ready for the general public yet.
261 B<If you're on the DJGPP port of DOS,>
265 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
266 will both uncompress and unpack.
274 Go into the newly-created directory and type:
280 You will need the packages mentioned in F<README.dos>
281 in the Perl distribution.
285 While still in that directory, type:
289 You will need the packages mentioned in F<README.dos> in the Perl distribution.
293 B<If you're on OS/2,>
295 Get the EMX development suite and gzip/tar, from either Hobbes (
296 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
297 the instructions for Unix.
303 When downloading from CPAN, save your file with a F<.tgz>
304 extension instead of F<.tar.gz>. All other periods in the
305 filename should be replaced with underscores. For example,
306 C<Your-Module-1.33.tar.gz> should be downloaded as
307 C<Your-Module-1_33.tgz>.
313 gzip -d Your-Module.tgz
315 or, for zipped modules, type
317 unzip Your-Module.zip
319 Executables for gzip, zip, and VMStar ( Alphas:
320 http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
321 http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
324 are also available at ftp://ftp.digital.com/pub/VMS.
326 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
327 package. The former is a simple compression tool; the latter permits
328 creation of multi-file archives.
332 If you're using VMStar:
334 VMStar xf Your-Module.tar
336 Or, if you're fond of VMS command syntax:
338 tar/extract/verbose Your_Module.tar
342 Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at http://www.madgoat.com ). Then type this to create the
343 DESCRIP.MMS for the module:
347 Now you're ready to build:
352 Substitute C<mmk> for C<mms> above if you're using MMK.
360 Substitute C<mmk> for C<mms> above if you're using MMK.
366 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
371 Decompress the file with C<gzip -d yourmodule.tar.gz>
373 You can get gzip from
374 http://www.s390.ibm.com/products/oe/bpxqp1.html.
378 Unpack the result with
380 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
382 The BUILD and INSTALL steps are identical to those for Unix. Some
383 modules generate Makefiles that work better with GNU make, which is
384 available from http://www.mks.com/s390/gnu/index.htm.
390 If you have any suggested changes for this page, let me know. Please
391 don't send me mail asking for help on how to install your modules.
392 There are too many modules, and too few Orwants, for me to be able to
393 answer or even acknowledge all your questions. Contact the module
394 author instead, or post to comp.lang.perl.modules, or ask someone
395 familiar with Perl on your operating system.
403 The Perl Journal, http://tpj.com
405 with invaluable help from Brandon Allbery, Charles Bailey, Graham
406 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
407 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
408 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
409 Sugalski, Larry Virden, and Ilya Zakharevich.
415 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
417 Permission is granted to make and distribute verbatim copies of this
418 documentation provided the copyright notice and this permission notice are
419 preserved on all copies.
421 Permission is granted to copy and distribute modified versions of this
422 documentation under the conditions for verbatim copying, provided also
423 that they are marked clearly as modified versions, that the authors'
424 names and title are unchanged (though subtitles and additional
425 authors' names may be added), and that the entire resulting derived
426 work is distributed under the terms of a permission notice identical
429 Permission is granted to copy and distribute translations of this
430 documentation into another language, under the above conditions for