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 Perl maintains a record of all module installations. To look at
95 this list, simply type:
99 That's all you need to do on Unix systems with dynamic linking.
100 Most Unix systems have dynamic linking--if yours doesn't, or if for
101 another reason you have a statically-linked perl, I<and> the
102 module requires compilation, you'll need to build a new Perl binary
103 that includes the module. Again, you'll probably need to be root.
107 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
111 You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
112 decompress and unpack modules.
116 If you used WinZip, this was already done for you.
120 Does the module require compilation (i.e. does it have files
121 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on
122 your own. You can try compiling it yourself if you have a C compiler.
123 If you're successful, consider uploading the resulting binary to
124 CPAN for others to use. If it doesn't, go to INSTALL.
128 Copy the module into your Perl's I<lib> directory. That'll be one
129 of the directories you see when you type
131 perl -e 'print "@INC"'
135 B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
139 When you download the module, make sure it ends in either
140 F<.tar.gz> or F<.zip>. Windows browsers sometimes
141 download C<.tar.gz> files as C<_tar.tar>, because
142 early versions of Windows prohibited more than one dot in a filename.
144 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
145 decompress and unpack modules.
147 Or, you can use InfoZip's C<unzip> utility (
148 http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
149 C<unzip yourmodule.zip> in your shell.
151 Or, if you have a working C<tar> and C<gzip>, you can
154 gzip -cd yourmodule.tar.gz | tar xvf -
156 in the shell to decompress C<yourmodule.tar.gz>. This will
157 UNPACK your module as well.
161 The methods in DECOMPRESS will have done this for you.
165 Go into the newly-created directory and type:
171 Depending on your perl configuration, C<dmake> might not be
172 available. You might have to substitute whatever C<perl
173 -V:make> says. (Usually, that will be C<nmake> or
178 While still in that directory, type:
184 B<If you're using a Macintosh,>
188 In general, all Macintosh decompression utilities mentioned here
189 can be found in the Info-Mac Hyperarchive
190 ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
191 Specifically the "Compress & Translate" listing
192 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
195 You can either use the shareware B<StuffIt Expander> program
196 ( http://www.aladdinsys.com/expander/ )
197 in combination with I<DropStuff with Expander Enhancer>
198 ( http://www.aladdinsys.com/dropstuff/ )
199 or the freeware B<MacGzip> program (
200 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
205 If you're using DropStuff or Stuffit, you can just extract the tar
206 archive. Otherwise, you can use the freeware B<suntar> or I<Tar> (
207 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
211 Does the module require compilation?
215 Overview: You need MPW and a combination of new and old CodeWarrior
216 compilers for MPW and libraries. Makefiles created for building under
217 MPW use Metrowerks compilers. It's most likely possible to build
218 without other compilers, but it has not been done successfully, to our
219 knowledge. Read the documentation in I<MacPerl: Power and Ease> (
220 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
221 an existing precompiled binary, or hire someone to build it for you.
223 Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
224 to build it for you. To subscribe to the mac-perl mailing list, send
225 mail to mac-perl-request@iis.ee.ethz.ch.
227 2. If the module doesn't require compilation, go to INSTALL.
231 Make sure the newlines for the modules are in Mac format, not Unix format.
232 If they are not then you might have decompressed them incorrectly. Check
233 your decompression and unpacking utilities settings to make sure they are
234 translating text files properly.
236 As a last resort, you can use the perl one-liner:
238 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
242 Move the files manually into the correct folders.
244 Move the files to their final destination: This will
245 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
246 C<HD:MacPerl folder:site_lib:>). You can add new paths to
247 the default C<@INC> in the Preferences menu item in the
248 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
249 automagically). Create whatever directory structures are required
250 (i.e., for C<Some::Module>, create
251 C<$ENV{MACPERL}site_lib:Some:> and put
252 C<Module.pm> in that directory).
254 Run the following script (or something like it):
258 my $dir = "${MACPERL}site_perl";
259 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
261 Eventually there should be a way to automate the installation process; some
262 solutions exist, but none are ready for the general public yet.
266 B<If you're on the DJGPP port of DOS,>
270 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
271 will both uncompress and unpack.
279 Go into the newly-created directory and type:
285 You will need the packages mentioned in F<README.dos>
286 in the Perl distribution.
290 While still in that directory, type:
294 You will need the packages mentioned in F<README.dos> in the Perl distribution.
298 B<If you're on OS/2,>
300 Get the EMX development suite and gzip/tar, from either Hobbes (
301 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
302 the instructions for Unix.
308 When downloading from CPAN, save your file with a F<.tgz>
309 extension instead of F<.tar.gz>. All other periods in the
310 filename should be replaced with underscores. For example,
311 C<Your-Module-1.33.tar.gz> should be downloaded as
312 C<Your-Module-1_33.tgz>.
318 gzip -d Your-Module.tgz
320 or, for zipped modules, type
322 unzip Your-Module.zip
324 Executables for gzip, zip, and VMStar ( Alphas:
325 http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
326 http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
329 are also available at ftp://ftp.digital.com/pub/VMS.
331 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
332 package. The former is a simple compression tool; the latter permits
333 creation of multi-file archives.
337 If you're using VMStar:
339 VMStar xf Your-Module.tar
341 Or, if you're fond of VMS command syntax:
343 tar/extract/verbose Your_Module.tar
347 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
348 DESCRIP.MMS for the module:
352 Now you're ready to build:
357 Substitute C<mmk> for C<mms> above if you're using MMK.
365 Substitute C<mmk> for C<mms> above if you're using MMK.
371 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
376 Decompress the file with C<gzip -d yourmodule.tar.gz>
378 You can get gzip from
379 http://www.s390.ibm.com/products/oe/bpxqp1.html.
383 Unpack the result with
385 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
387 The BUILD and INSTALL steps are identical to those for Unix. Some
388 modules generate Makefiles that work better with GNU make, which is
389 available from http://www.mks.com/s390/gnu/index.htm.
395 If you have any suggested changes for this page, let me know. Please
396 don't send me mail asking for help on how to install your modules.
397 There are too many modules, and too few Orwants, for me to be able to
398 answer or even acknowledge all your questions. Contact the module
399 author instead, or post to comp.lang.perl.modules, or ask someone
400 familiar with Perl on your operating system.
408 The Perl Journal, http://tpj.com
410 with invaluable help from Brandon Allbery, Charles Bailey, Graham
411 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
412 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
413 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
414 Sugalski, Larry Virden, and Ilya Zakharevich.
420 Copyright (C) 1998 Jon Orwant. All Rights Reserved.
422 Permission is granted to make and distribute verbatim copies of this
423 documentation provided the copyright notice and this permission notice are
424 preserved on all copies.
426 Permission is granted to copy and distribute modified versions of this
427 documentation under the conditions for verbatim copying, provided also
428 that they are marked clearly as modified versions, that the authors'
429 names and title are unchanged (though subtitles and additional
430 authors' names may be added), and that the entire resulting derived
431 work is distributed under the terms of a permission notice identical
434 Permission is granted to copy and distribute translations of this
435 documentation into another language, under the above conditions for