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:
231 perl -i.bak -pe 's/(?:\015)?\012/\015/g' filenames
235 Move the files manually into the correct folders.
237 Move the files to their final destination: This will
238 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
239 C<HD:MacPerl folder:site_lib:>). You can add new paths to
240 the default C<@INC> in the Preferences menu item in the
241 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
242 automagically). Create whatever directory structures are required
243 (i.e., for C<Some::Module>, create
244 C<$ENV{MACPERL}site_lib:Some:> and put
245 C<Module.pm> in that directory).
247 Run the following script (or something like it):
251 my $dir = "${MACPERL}site_perl";
252 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
254 Eventually there should be a way to automate the installation process; some
255 solutions exist, but none are ready for the general public yet.
259 B<If you're on the DJGPP port of DOS,>
263 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
264 will both uncompress and unpack.
272 Go into the newly-created directory and type:
278 You will need the packages mentioned in C<Readme.dos>
279 in the Perl distribution.
283 While still in that directory, type:
287 You will need the packages mentioned in Readme.dos in the Perl distribution.
291 B<If you're on OS/2,>
293 Get the EMX development suite and gzip/tar, from either Hobbes (
294 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
295 the instructions for Unix.
301 When downloading from CPAN, save your file with a C<.tgz>
302 extension instead of C<.tar.gz>. All other periods in the
303 filename should be replaced with underscores. For example,
304 C<Your-Module-1.33.tar.gz> should be downloaded as
305 C<Your-Module-1_33.tgz>.
311 gzip -d Your-Module.tgz
313 or, for zipped modules, type
315 unzip Your-Module.zip
317 Executables for gzip, zip, and VMStar ( Alphas:
318 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
319 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
322 are also available at ftp://ftp.digital.com/pub/VMS.
324 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
325 package. The former is a simple compression tool; the latter permits
326 creation of multi-file archives.
330 If you're using VMStar:
332 VMStar xf Your-Module.tar
334 Or, if you're fond of VMS command syntax:
336 tar/extract/verbose Your_Module.tar
340 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
341 DESCRIP.MMS for the module:
345 Now you're ready to build:
350 Substitute C<mmk> for C<mms> above if you're using MMK.
358 Substitute C<mmk> for C<mms> above if you're using MMK.
364 Introduce the .tar.gz file into an HFS as binary; don't translate from
369 Decompress the file with C<gzip -d yourmodule.tar.gz>
371 You can get gzip from
372 http://www.s390.ibm.com/products/oe/bpxqp1.html.
376 Unpack the result with
378 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
380 The BUILD and INSTALL steps are identical to those for Unix. Some
381 modules generate Makefiles that work better with GNU make, which is
382 available from http://www.mks.com/s390/gnu/index.htm.
388 If you have any suggested changes for this page, let me know. Please
389 don't send me mail asking for help on how to install your modules.
390 There are too many modules, and too few Orwants, for me to be able to
391 answer or even acknowledge all your questions. Contact the module
392 author instead, or post to comp.lang.perl.modules, or ask someone
393 familiar with Perl on your operating system.
401 The Perl Journal, http://tpj.com
403 with invaluable help from Brandon Allbery, Charles Bailey, Graham
404 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
405 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
406 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
407 Sugalski, Larry Virden, and Ilya Zakharevich.
413 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
415 Permission is granted to make and distribute verbatim copies of this
416 documentation provided the copyright notice and this permission notice are
417 preserved on all copies.
419 Permission is granted to copy and distribute modified versions of this
420 documentation under the conditions for verbatim copying, provided also
421 that they are marked clearly as modified versions, that the authors'
422 names and title are unchanged (though subtitles and additional
423 authors' names may be added), and that the entire resulting derived
424 work is distributed under the terms of a permission notice identical
427 Permission is granted to copy and distribute translations of this
428 documentation into another language, under the above conditions for