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 of
9 Perl code that they think will be useful to the world, they register
10 as a Perl developer at http://www.perl.com/CPAN/modules/04pause.html
11 so that they can then upload their code to the CPAN. The CPAN is the
12 Comprehensive Perl Archive Network and can be accessed at
13 http://www.perl.com/CPAN/.
15 This documentation is for people who want to download CPAN modules
16 and install them on their own computer.
20 You have a file ending in .tar.gz (or, less often, .zip). You know
21 there's a tasty module inside. There are four steps you must now
26 =item B<DECOMPRESS> the file
28 =item B<UNPACK> the file into a directory
30 =item B<BUILD> the module (sometimes unnecessary)
32 =item B<INSTALL> the module.
36 Here's how to perform each step for each operating system. This is
37 I<not> a substitute for reading the README and INSTALL files that
38 might have come with your module!
40 Also note that these instructions are tailored for installing the
41 module into your system's repository of Perl modules. But you can
42 install modules into any directory you wish. For instance, where I
43 say C<perl Makefile.PL>, you can substitute C<perl
44 Makefile.PL PREFIX=/my/perl_directory> to install the modules
45 into C</my/perl_directory>. Then you can use the modules
46 from your Perl programs with C<use lib
47 "/my/perl_directory/lib/site_perl";> or sometimes just C<use
48 "/my/perl_directory";>.
56 You can use Andreas Koenig's CPAN module
57 ( http://www.perl.com/CPAN/modules/by-module/CPAN )
58 to automate the following steps, from DECOMPRESS through INSTALL.
62 Decompress the file with C<gzip -d yourmodule.tar.gz>
64 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
66 Or, you can combine this step with the next to save disk space:
68 gzip -dc yourmodule.tar.gz | tar -xof -
72 Unpack the result with C<tar -xof yourmodule.tar>
76 Go into the newly-created directory and type:
84 While still in that directory, type:
88 Make sure you have the appropriate permissions to install the module
89 in your Perl 5 library directory. Often, you'll need to be root.
91 That's all you need to do on Unix systems with dynamic linking.
92 Most Unix systems have dynamic linking -- if yours doesn't, or if for
93 another reason you have a statically-linked perl, B<and> the
94 module requires compilation, you'll need to build a new Perl binary
95 that includes the module. Again, you'll probably need to be root.
99 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
103 You can use the shareware Winzip ( http://www.winzip.com ) to
104 decompress and unpack modules.
108 If you used WinZip, this was already done for you.
112 Does the module require compilation (i.e. does it have files
113 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on
114 your own. You can try compiling it yourself if you have a C compiler.
115 If you're successful, consider uploading the resulting binary to the
116 CPAN for others to use. If it doesn't, go to INSTALL.
120 Copy the module into your Perl's I<lib> directory. That'll be one
121 of the directories you see when you type
123 perl -e 'print "@INC"'
127 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
131 When you download the module, make sure it ends in either
132 C<.tar.gz> or C<.zip>. Windows browsers sometimes
133 download C<.tar.gz> files as C<_tar.tar>, because
134 early versions of Windows prohibited more than one dot in a filename.
136 You can use the shareware WinZip ( http://www.winzip.com ) to
137 decompress and unpack modules.
139 Or, you can use InfoZip's C<unzip> utility (
140 http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
141 C<.zip> files; type C<unzip yourmodule.zip> in
144 Or, if you have a working C<tar> and C<gzip>, you can
147 gzip -cd yourmodule.tar.gz | tar xvf -
149 in the shell to decompress C<yourmodule.tar.gz>. This will
150 UNPACK your module as well.
154 All of the methods in DECOMPRESS will have done this for you.
158 Go into the newly-created directory and type:
164 Depending on your perl configuration, C<dmake> might not be
165 available. You might have to substitute whatever C<perl
166 -V:make> says. (Usually, that will be C<nmake> or
171 While still in that directory, type:
177 B<If you're using a Macintosh,>
181 In general, all Macintosh decompression utilities mentioned here
182 can be found in the Info-Mac Hyperarchive
183 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
184 Specificly the "Commpress & Translate" listing
185 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
188 You can either use the shareware StuffIt Expander
189 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/stuffit-expander-401.hqx )
190 in combination with I<DropStuff with Expander Enhancer>
191 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/drop-stuff-with-ee-40.hqx )
192 or the freeware MacGzip (
193 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
198 If you're using DropStuff or Stuffit, you can just extract the tar
199 archive. Otherwise, you can use the freeware I<suntar>
200 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/suntar-221.hqx )
201 or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/tar-40b.hqx ).
205 Does the module require compilation?
209 Overview: You need MPW and a combination of new and old CodeWarrior
210 compilers for MPW and libraries. Makefiles created for building under
211 MPW use the Metrowerks compilers. It's most likely possible to build
212 without other compilers, but it has not been done successfully, to our
213 knowledge. Read the documentation in MacPerl: Power and Ease (
214 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
215 an existing precompiled binary, or hire someone to build it for you.
217 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
218 to build it for you. To subscribe to the mac-perl mailing list, send
219 mail to mac-perl-request@iis.ee.ethz.ch.
221 2. If the module doesn't require compilation, go to INSTALL.
225 Make sure the newlines for the modules are in Mac format, not Unix format.
226 If they are not then you might have decompressed them incorrectly. Check
227 your decompression and unpacking utilities settings to make sure they are
228 translating text files properly.
229 As a last resort, you can use the perl one-liner: perl -i.bak -pe
230 's/(?:\015)?\012/\015/g' <filenames> on the source files.
232 Move the files manually into the correct folders.
234 Move the files to their final destination: This will
235 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
236 C<HD:MacPerl folder:site_lib:>). You can add new paths to
237 the default C<@INC> in the Preferences menu item in the
238 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
239 automagically). Create whatever directory structures are required
240 (i.e., for C<Some::Module>, create
241 C<$ENV{MACPERL}site_lib:Some:> and put
242 C<Module.pm> in that directory).
244 Run the following script (or something like it):
248 my $dir = "${MACPERL}site_perl";
249 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
251 Eventually there should be a way to automate the installation process; some
252 solutions exist, but none are ready for the general public yet.
256 B<If you're on the DJGPP port of DOS,>
260 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
261 will both uncompress and unpack.
269 Go into the newly-created directory and type:
275 You will need the packages mentioned in C<Readme.dos>
276 in the Perl distribution.
280 While still in that directory, type:
284 You will need the packages mentioned in Readme.dos in the Perl distribution.
288 B<If you're on OS/2,>
290 Get the EMX development suite and gzip/tar, from either Hobbes (
291 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
292 the instructions for Unix.
298 When downloading from CPAN, save your file with a C<.tgz>
299 extension instead of C<.tar.gz>. All other periods in the
300 filename should be replaced with underscores. For example,
301 C<Your-Module-1.33.tar.gz> should be downloaded as
302 C<Your-Module-1_33.tgz>.
308 gzip -d Your-Module.tgz
310 or, for zipped modules, type
312 unzip Your-Module.zip
314 Executables for gzip, zip, and VMStar ( Alphas:
315 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
316 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
319 are also available at ftp://ftp.digital.com/pub/VMS.
321 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
322 package. The former is a simple compression tool; the latter permits
323 creation of multi-file archives.
327 If you're using VMStar:
329 VMStar xf Your-Module.tar
331 Or, if you're fond of VMS command syntax:
333 tar/extract/verbose Your_Module.tar
337 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
338 DESCRIP.MMS for the module:
342 Now you're ready to build:
347 Substitute C<mmk> for C<mms> above if you're using MMK.
355 Substitute C<mmk> for C<mms> above if you're using MMK.
361 Introduce the .tar.gz file into an HFS as binary; don't translate from
366 Decompress the file with C<gzip -d yourmodule.tar.gz>
368 You can get gzip from
369 http://www.s390.ibm.com/products/oe/bpxqp1.html.
373 Unpack the result with
375 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
377 The BUILD and INSTALL steps are identical to those for Unix. Some
378 modules generate Makefiles that work better with GNU make, which is
379 available from http://www.mks.com/s390/gnu/index.htm.
385 If you have any suggested changes for this page, let me know. Please
386 don't send me mail asking for help on how to install your modules.
387 There are too many modules, and too few Orwants, for me to be able to
388 answer or even acknowledge all your questions. Contact the module
389 author instead, or post to comp.lang.perl.modules, or ask someone
390 familiar with Perl on your operating system.
398 The Perl Journal, http://tpj.com
400 with invaluable help from Brandon Allbery, Charles Bailey, Graham
401 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
402 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
403 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
404 Sugalski, Larry Virden, and Ilya Zakharevich.
410 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
412 Permission is granted to make and distribute verbatim copies of this
413 documentation provided the copyright notice and this permission notice are
414 preserved on all copies.
416 Permission is granted to copy and distribute modified versions of this
417 documentation under the conditions for verbatim copying, provided also
418 that they are marked clearly as modified versions, that the authors'
419 names and title are unchanged (though subtitles and additional
420 authors' names may be added), and that the entire resulting derived
421 work is distributed under the terms of a permission notice identical
424 Permission is granted to copy and distribute translations of this
425 documentation into another language, under the above conditions for