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 You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in
182 combination with I<DropStuff with Expander Enhancer>
183 (shareware), or the freeware MacGzip (
184 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
188 If you're using DropStuff or Stuffit, you can just extract the tar
189 archive. Otherwise, you can use the freeware I<suntar> (
190 http://www.cirfid.unibo.it/~speranza ).
194 Does the module require compilation?
198 Overview: You need MPW and a combination of new and old CodeWarrior
199 compilers for MPW and libraries. Makefiles created for building under
200 MPW use the Metrowerks compilers. It's most likely possible to build
201 without other compilers, but it has not been done successfully, to our
202 knowledge. Read the documentation in MacPerl: Power and Ease (
203 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
204 an existing precompiled binary, or hire someone to build it for you.
206 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
207 to build it for you. To subscribe to the mac-perl mailing list, send
208 mail to mac-perl-request@iis.ee.ethz.ch.
210 2. If the module doesn't require compilation, go to INSTALL.
214 Make sure the newlines for the modules are in Mac format, not Unix format.
215 Move the files manually into the correct folders.
217 Move the files to their final destination: This will
218 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
219 C<HD:MacPerl folder:site_lib:>). You can add new paths to
220 the default C<@INC> in the Preferences menu item in the
221 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
222 automagically). Create whatever directory structures are required
223 (i.e., for C<Some::Module>, create
224 C<$ENV{MACPERL}site_lib:Some:> and put
225 C<Module.pm> in that directory).
227 Run the following script (or something like it):
231 my $dir = "${MACPERL}site_perl";
232 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
234 Eventually there should be a way to automate the installation process; some
235 solutions exist, but none are ready for the general public yet.
239 B<If you're on the DJGPP port of DOS,>
243 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
244 will both uncompress and unpack.
252 Go into the newly-created directory and type:
258 You will need the packages mentioned in C<Readme.dos>
259 in the Perl distribution.
263 While still in that directory, type:
267 You will need the packages mentioned in Readme.dos in the Perl distribution.
271 B<If you're on OS/2,>
273 Get the EMX development suite and gzip/tar, from either Hobbes (
274 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
275 the instructions for Unix.
281 When downloading from CPAN, save your file with a C<.tgz>
282 extension instead of C<.tar.gz>. All other periods in the
283 filename should be replaced with underscores. For example,
284 C<Your-Module-1.33.tar.gz> should be downloaded as
285 C<Your-Module-1_33.tgz>.
291 gzip -d Your-Module.tgz
293 or, for zipped modules, type
295 unzip Your-Module.zip
297 Executables for gzip, zip, and VMStar ( Alphas:
298 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
299 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
302 are also available at ftp://ftp.digital.com/pub/VMS.
304 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
305 package. The former is a simple compression tool; the latter permits
306 creation of multi-file archives.
310 If you're using VMStar:
312 VMStar xf Your-Module.tar
314 Or, if you're fond of VMS command syntax:
316 tar/extract/verbose Your_Module.tar
320 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
321 DESCRIP.MMS for the module:
325 Now you're ready to build:
330 Substitute C<mmk> for C<mms> above if you're using MMK.
338 Substitute C<mmk> for C<mms> above if you're using MMK.
344 Introduce the .tar.gz file into an HFS as binary; don't translate from
349 Decompress the file with C<gzip -d yourmodule.tar.gz>
351 You can get gzip from
352 http://www.s390.ibm.com/products/oe/bpxqp1.html.
356 Unpack the result with
358 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
360 The BUILD and INSTALL steps are identical to those for Unix. Some
361 modules generate Makefiles that work better with GNU make, which is
362 available from http://www.mks.com/s390/gnu/index.htm.
368 If you have any suggested changes for this page, let me know. Please
369 don't send me mail asking for help on how to install your modules.
370 There are too many modules, and too few Orwants, for me to be able to
371 answer or even acknowledge all your questions. Contact the module
372 author instead, or post to comp.lang.perl.modules, or ask someone
373 familiar with Perl on your operating system.
381 The Perl Journal, http://tpj.com
383 with invaluable help from Brandon Allbery, Charles Bailey, Graham
384 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
385 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
386 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
387 Sugalski, Larry Virden, and Ilya Zakharevich.
393 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
395 Permission is granted to make and distribute verbatim copies of this
396 documentation provided the copyright notice and this permission notice are
397 preserved on all copies.
399 Permission is granted to copy and distribute modified versions of this
400 documentation under the conditions for verbatim copying, provided also
401 that they are marked clearly as modified versions, that the authors'
402 names and title are unchanged (though subtitles and additional
403 authors' names may be added), and that the entire resulting derived
404 work is distributed under the terms of a permission notice identical
407 Permission is granted to copy and distribute translations of this
408 documentation into another language, under the above conditions for