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
27 =item B<UNPACK> the file into a directory
28 =item B<BUILD> the module (sometimes unnecessary)
29 =item B<INSTALL> the module.
33 Here's how to perform each step for each operating system. This is
34 I<not> a substitute for reading the README and INSTALL files that
35 might have come with your module!
37 Also note that these instructions are tailored for installing the
38 module into your system's repository of Perl modules. But you can
39 install modules into any directory you wish. For instance, where I
40 say C<perl Makefile.PL>, you can substitute C<perl
41 Makefile.PL PREFIX=/my/perl_directory> to install the modules
42 into C</my/perl_directory>. Then you can use the modules
43 from your Perl programs with C<use lib
44 "/my/perl_directory/lib/site_perl";> or sometimes just C<use
45 "/my/perl_directory";>.
53 You can use Andreas Koenig's CPAN module
54 ( http://www.perl.com/CPAN/modules/by-module/CPAN )
55 to automate the following steps, from DECOMPRESS through INSTALL.
59 Decompress the file with C<gzip -d yourmodule.tar.gz>
61 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
63 Or, you can combine this step with the next to save disk space:
65 gzip -dc yourmodule.tar.gz | tar -xof -
69 Unpack the result with C<tar -xof yourmodule.tar>
73 Go into the newly-created directory and type:
81 While still in that directory, type:
85 Make sure you have the appropriate permissions to install the module
86 in your Perl 5 library directory. Often, you'll need to be root.
88 That's all you need to do on Unix systems with dynamic linking.
89 Most Unix systems have dynamic linking -- if yours doesn't, or if for
90 another reason you have a statically-linked perl, B<and> the
91 module requires compilation, you'll need to build a new Perl binary
92 that includes the module. Again, you'll probably need to be root.
96 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
100 You can use the shareware Winzip ( http://www.winzip.com ) to
101 decompress and unpack modules.
105 If you used WinZip, this was already done for you.
109 Does the module require compilation (i.e. does it have files
110 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on
111 your own. You can try compiling it yourself if you have a C compiler.
112 If you're successful, consider uploading the resulting binary to the
113 CPAN for others to use. If it doesn't, go to INSTALL.
117 Copy the module into your Perl's I<lib> directory. That'll be one
118 of the directories you see when you type
120 perl -e 'print "@INC"'
124 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
128 When you download the module, make sure it ends in either
129 C<.tar.gz> or C<.zip>. Windows browsers sometimes
130 download C<.tar.gz> files as C<_tar.tar>, because
131 early versions of Windows prohibited more than one dot in a filename.
133 You can use the shareware WinZip ( http://www.winzip.com ) to
134 decompress and unpack modules.
136 Or, you can use InfoZip's C<unzip> utility (
137 http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
138 C<.zip> files; type C<unzip yourmodule.zip> in
141 Or, if you have a working C<tar> and C<gzip>, you can
144 gzip -cd yourmodule.tar.gz | tar xvf -
146 in the shell to decompress C<yourmodule.tar.gz>. This will
147 UNPACK your module as well.
151 All of the methods in DECOMPRESS will have done this for you.
155 Go into the newly-created directory and type:
161 Depending on your perl configuration, C<dmake> might not be
162 available. You might have to substitute whatever C<perl
163 -V:make> says. (Usually, that will be C<nmake> or
168 While still in that directory, type:
174 B<If you're using a Macintosh,>
178 You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in
179 combination with I<DropStuff with Expander Enhancer>
180 (shareware), or the freeware MacGzip (
181 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
185 If you're using DropStuff or Stuffit, you can just extract the tar
186 archive. Otherwise, you can use the freeware I<suntar> (
187 http://www.cirfid.unibo.it/~speranza ).
191 Does the module require compilation?
195 Overview: You need MPW and a combination of new and old CodeWarrior
196 compilers for MPW and libraries. Makefiles created for building under
197 MPW use the Metrowerks compilers. It's most likely possible to build
198 without other compilers, but it has not been done successfully, to our
199 knowledge. Read the documentation in MacPerl: Power and Ease (
200 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
201 an existing precompiled binary, or hire someone to build it for you.
203 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
204 to build it for you. To subscribe to the mac-perl mailing list, send
205 mail to mac-perl-request@iis.ee.ethz.ch.
207 2. If the module doesn't require compilation, go to INSTALL.
211 Make sure the newlines for the modules are in Mac format, not Unix format.
212 Move the files manually into the correct folders.
214 Move the files to their final destination: This will
215 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
216 C<HD:MacPerl folder:site_lib:>). You can add new paths to
217 the default C<@INC> in the Preferences menu item in the
218 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
219 automagically). Create whatever directory structures are required
220 (i.e., for C<Some::Module>, create
221 C<$ENV{MACPERL}site_lib:Some:> and put
222 C<Module.pm> in that directory).
224 Run the following script (or something like it):
228 my $dir = "${MACPERL}site_perl";
229 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
231 Eventually there should be a way to automate the installation process; some
232 solutions exist, but none are ready for the general public yet.
236 B<If you're on the DJGPP port of DOS,>
240 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
241 will both uncompress and unpack.
249 Go into the newly-created directory and type:
255 You will need the packages mentioned in C<Readme.dos>
256 in the Perl distribution.
260 While still in that directory, type:
264 You will need the packages mentioned in Readme.dos in the Perl distribution.
268 B<If you're on OS/2,>
270 Get the EMX development suite and gzip/tar, from either Hobbes (
271 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
272 the instructions for Unix.
278 When downloading from CPAN, save your file with a C<.tgz>
279 extension instead of C<.tar.gz>. All other periods in the
280 filename should be replaced with underscores. For example,
281 C<Your-Module-1.33.tar.gz> should be downloaded as
282 C<Your-Module-1_33.tgz>.
288 gzip -d Your-Module.tgz
290 or, for zipped modules, type
292 unzip Your-Module.zip
294 Executables for gzip, zip, and VMStar ( Alphas:
295 http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
296 http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
299 are also available at ftp://ftp.digital.com/pub/VMS.
301 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
302 package. The former is a simple compression tool; the latter permits
303 creation of multi-file archives.
307 If you're using VMStar:
309 VMStar xf Your-Module.tar
311 Or, if you're fond of VMS command syntax:
313 tar/extract/verbose Your_Module.tar
317 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
318 DESCRIP.MMS for the module:
322 Now you're ready to build:
327 Substitute C<mmk> for C<mms> above if you're using MMK.
335 Substitute C<mmk> for C<mms> above if you're using MMK.
341 Introduce the .tar.gz file into an HFS as binary; don't translate from
346 Decompress the file with C<gzip -d yourmodule.tar.gz>
348 You can get gzip from
349 http://www.s390.ibm.com/products/oe/bpxqp1.html.
353 Unpack the result with
355 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
357 The BUILD and INSTALL steps are identical to those for Unix. Some
358 modules generate Makefiles that work better with GNU make, which is
359 available from http://www.mks.com/s390/gnu/index.htm.
365 If you have any suggested changes for this page, let me know. Please
366 don't send me mail asking for help on how to install your modules.
367 There are too many modules, and too few Orwants, for me to be able to
368 answer or even acknowledge all your questions. Contact the module
369 author instead, or post to comp.lang.perl.modules, or ask someone
370 familiar with Perl on your operating system.
378 The Perl Journal, http://tpj.com
380 with invaluable help from Brandon Allbery, Charles Bailey, Graham
381 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
382 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
383 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
384 Sugalski, Larry Virden, and Ilya Zakharevich.
390 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
392 Permission is granted to make and distribute verbatim copies of this
393 documentation provided the copyright notice and this permission notice are
394 preserved on all copies.
396 Permission is granted to copy and distribute modified versions of this
397 documentation under the conditions for verbatim copying, provided also
398 that they are marked clearly as modified versions, that the authors'
399 names and title are unchanged (though subtitles and additional
400 authors' names may be added), and that the entire resulting derived
401 work is distributed under the terms of a permission notice identical
404 Permission is granted to copy and distribute translations of this
405 documentation into another language, under the above conditions for