This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POD nitpicks.
[perl5.git] / pod / perlmodinstall.pod
CommitLineData
fb9cefb4
GS
1=head1 NAME
2
3perlmodinstall - Installing CPAN Modules
4
5=head1 DESCRIPTION
6
7You can think of a module as the fundamental unit of reusable Perl
b3539c74
JH
8code; see L<perlmod> for details. Whenever anyone creates a chunk of
9Perl code that they think will be useful to the world, they register
a74498e7 10as a Perl developer at http://www.cpan.org/modules/04pause.html
b3539c74
JH
11so that they can then upload their code to the CPAN. The CPAN is the
12Comprehensive Perl Archive Network and can be accessed at
91826056 13http://www.cpan.org/ , and searched at http://search.cpan.org/ .
fb9cefb4
GS
14
15This documentation is for people who want to download CPAN modules
16and install them on their own computer.
17
18=head2 PREAMBLE
19
b3539c74
JH
20First, are you sure that the module isn't already on your system? Try
21C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
6c1c521a 22instance, C<perl -MCGI::Carp -e 1>.)
b3539c74
JH
23
24If you don't see an error message, you have the module. (If you do
25see an error message, it's still possible you have the module, but
26that it's not in your path, which you can display with C<perl -e
27"print qq(@INC)">.) For the remainder of this document, we'll assume
28that you really honestly truly lack an installed module, but have
29found it on the CPAN.
30
31So now you have a file ending in .tar.gz (or, less often, .zip). You
32know there's a tasty module inside. There are four steps you must now
33take:
fb9cefb4
GS
34
35=over 5
36
37=item B<DECOMPRESS> the file
637e9122 38
fb9cefb4 39=item B<UNPACK> the file into a directory
637e9122 40
fb9cefb4 41=item B<BUILD> the module (sometimes unnecessary)
637e9122 42
fb9cefb4
GS
43=item B<INSTALL> the module.
44
45=back
46
47Here's how to perform each step for each operating system. This is
91826056 48<not> a substitute for reading the README and INSTALL files that
fb9cefb4
GS
49might have come with your module!
50
51Also note that these instructions are tailored for installing the
ac036724 52module into your system's repository of Perl modules, but you can
fb9cefb4 53install modules into any directory you wish. For instance, where I
b3539c74
JH
54say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL
55PREFIX=/my/perl_directory> to install the modules into
f703fc96 56F</my/perl_directory>. Then you can use the modules from your Perl
b3539c74
JH
57programs with C<use lib "/my/perl_directory/lib/site_perl";> or
58sometimes just C<use "/my/perl_directory";>. If you're on a system
59that requires superuser/root access to install modules into the
60directories you see when you type C<perl -e "print qq(@INC)">, you'll
61want to install them into a local directory (such as your home
91826056 62directory) and use this approach.
fb9cefb4
GS
63
64=over 4
65
66=item *
67
8e30f651 68B<If you're on a Unix or Unix-like system,>
fb9cefb4 69
91826056
JH
70You can use Andreas Koenig's CPAN module
71( http://www.cpan.org/modules/by-module/CPAN )
fb9cefb4
GS
72to automate the following steps, from DECOMPRESS through INSTALL.
73
91826056 74A. DECOMPRESS
fb9cefb4
GS
75
76Decompress the file with C<gzip -d yourmodule.tar.gz>
77
1577cd80 78You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
fb9cefb4
GS
79
80Or, you can combine this step with the next to save disk space:
81
82 gzip -dc yourmodule.tar.gz | tar -xof -
83
84B. UNPACK
85
86Unpack the result with C<tar -xof yourmodule.tar>
87
88C. BUILD
89
90Go into the newly-created directory and type:
91
92 perl Makefile.PL
fb9cefb4
GS
93 make test
94
91826056 95or
b3539c74
JH
96
97 perl Makefile.PL PREFIX=/my/perl_directory
98
99to install it locally. (Remember that if you do this, you'll have to
100put C<use lib "/my/perl_directory";> near the top of the program that
101is to use this module.
102
fb9cefb4
GS
103D. INSTALL
104
105While still in that directory, type:
106
107 make install
108
b3539c74 109Make sure you have the appropriate permissions to install the module
fb9cefb4
GS
110in your Perl 5 library directory. Often, you'll need to be root.
111
112That's all you need to do on Unix systems with dynamic linking.
ac036724 113Most Unix systems have dynamic linking. If yours doesn't, or if for
b3539c74 114another reason you have a statically-linked perl, B<and> the
fb9cefb4
GS
115module requires compilation, you'll need to build a new Perl binary
116that includes the module. Again, you'll probably need to be root.
117
118=item *
119
f321be7e 120B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),>
b3539c74
JH
121
122First, type C<ppm> from a shell and see whether ActiveState's PPM
123repository has your module. If so, you can install it with C<ppm> and
124you won't have to bother with any of the other steps here. You might
125be able to use the CPAN instructions from the "Unix or Linux" section
126above as well; give it a try. Otherwise, you'll have to follow the
127steps below.
fb9cefb4
GS
128
129 A. DECOMPRESS
130
b3539c74 131You can use the shareware Winzip ( http://www.winzip.com ) to
fb9cefb4
GS
132decompress and unpack modules.
133
134 B. UNPACK
135
136If you used WinZip, this was already done for you.
137
138 C. BUILD
139
376270a4 140You'll need the C<nmake> utility, available at
cb9857f1 141http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
376270a4
MS
142or dmake, available on CPAN.
143http://search.cpan.org/dist/dmake/
144
145Does the module require compilation (i.e. does it have files that end
146in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
147officially tough for you, because you have to compile the module
ac036724 148yourself (no easy feat on Windows). You'll need a compiler such as
376270a4
MS
149Visual C++. Alternatively, you can download a pre-built PPM package
150from ActiveState.
151http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
152
153Go into the newly-created directory and type:
154
155 perl Makefile.PL
156 nmake test
157
fb9cefb4
GS
158
159 D. INSTALL
160
376270a4 161While still in that directory, type:
fb9cefb4 162
376270a4 163 nmake install
fb9cefb4
GS
164
165=item *
166
8e30f651 167B<If you're using a Macintosh with "Classic" MacOS and MacPerl,>
fb9cefb4 168
b3539c74 169
fb9cefb4
GS
170A. DECOMPRESS
171
b3539c74
JH
172First, make sure you have the latest B<cpan-mac> distribution (
173http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
174doing all of the steps. Read the cpan-mac directions carefully and
175install it. If you choose not to use cpan-mac for some reason, there
176are alternatives listed here.
be94a901 177
24dc5443
JH
178After installing cpan-mac, drop the module archive on the
179B<untarzipme> droplet, which will decompress and unpack for you.
be94a901 180
24dc5443 181B<Or>, you can either use the shareware B<StuffIt Expander> program
250a49b3 182( http://my.smithmicro.com/mac/stuffit/ )
19799a22 183or the freeware B<MacGzip> program (
fb9cefb4
GS
184http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
185
186B. UNPACK
187
24dc5443
JH
188If you're using untarzipme or StuffIt, the archive should be extracted
189now. B<Or>, you can use the freeware B<suntar> or I<Tar> (
6cecdcac 190http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
fb9cefb4
GS
191
192C. BUILD
193
24dc5443
JH
194Check the contents of the distribution.
195Read the module's documentation, looking for
196reasons why you might have trouble using it with MacPerl. Look for
197F<.xs> and F<.c> files, which normally denote that the distribution
198must be compiled, and you cannot install it "out of the box."
199(See L<"PORTABILITY">.)
200
24dc5443 201D. INSTALL
fb9cefb4 202
24dc5443
JH
203If you are using cpan-mac, just drop the folder on the
204B<installme> droplet, and use the module.
fb9cefb4 205
24dc5443 206B<Or>, if you aren't using cpan-mac, do some manual labor.
fb9cefb4
GS
207
208Make sure the newlines for the modules are in Mac format, not Unix format.
be94a901
GS
209If they are not then you might have decompressed them incorrectly. Check
210your decompression and unpacking utilities settings to make sure they are
211translating text files properly.
7711098a 212
24dc5443 213As a last resort, you can use the perl one-liner:
19799a22 214
24dc5443 215 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
7711098a
GS
216
217on the source files.
be94a901 218
24dc5443
JH
219Then move the files (probably just the F<.pm> files, though there
220may be some additional ones, too; check the module documentation)
221to their final destination: This will
fb9cefb4
GS
222most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
223C<HD:MacPerl folder:site_lib:>). You can add new paths to
224the default C<@INC> in the Preferences menu item in the
225MacPerl application (C<$ENV{MACPERL}site_lib:> is added
226automagically). Create whatever directory structures are required
227(i.e., for C<Some::Module>, create
228C<$ENV{MACPERL}site_lib:Some:> and put
229C<Module.pm> in that directory).
230
24dc5443 231Then run the following script (or something like it):
fb9cefb4
GS
232
233 #!perl -w
234 use AutoSplit;
235 my $dir = "${MACPERL}site_perl";
236 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
237
fb9cefb4
GS
238=item *
239
240B<If you're on the DJGPP port of DOS,>
241
242 A. DECOMPRESS
243
eb863851 244djtarx ( ftp://ftp.delorie.com/pub/djgpp/current/v2/ )
91826056 245will both uncompress and unpack.
fb9cefb4
GS
246
247 B. UNPACK
248
249See above.
250
251 C. BUILD
252
253Go into the newly-created directory and type:
254
255 perl Makefile.PL
fb9cefb4
GS
256 make test
257
91826056 258You will need the packages mentioned in F<README.dos>
fb9cefb4
GS
259in the Perl distribution.
260
261 D. INSTALL
262
263While still in that directory, type:
264
b3539c74 265 make install
91826056
JH
266
267You will need the packages mentioned in F<README.dos> in the Perl distribution.
fb9cefb4
GS
268
269=item *
270
271B<If you're on OS/2,>
272
273Get the EMX development suite and gzip/tar, from either Hobbes (
274http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
275the instructions for Unix.
276
277=item *
278
279B<If you're on VMS,>
280
b3539c74
JH
281When downloading from CPAN, save your file with a C<.tgz>
282extension instead of C<.tar.gz>. All other periods in the
fb9cefb4
GS
283filename should be replaced with underscores. For example,
284C<Your-Module-1.33.tar.gz> should be downloaded as
285C<Your-Module-1_33.tgz>.
286
287A. DECOMPRESS
288
91826056 289Type
fb9cefb4
GS
290
291 gzip -d Your-Module.tgz
292
91826056 293or, for zipped modules, type
fb9cefb4
GS
294
295 unzip Your-Module.zip
296
91826056
JH
297Executables for gzip, zip, and VMStar:
298
05e8c65e 299 http://www.hp.com/go/openvms/freeware/
fb9cefb4 300
91826056
JH
301and their source code:
302
303 http://www.fsf.org/order/ftp.html
fb9cefb4
GS
304
305Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
306package. The former is a simple compression tool; the latter permits
307creation of multi-file archives.
308
309B. UNPACK
310
311If you're using VMStar:
312
313 VMStar xf Your-Module.tar
314
315Or, if you're fond of VMS command syntax:
316
317 tar/extract/verbose Your_Module.tar
318
91826056 319C. BUILD
fb9cefb4 320
91826056
JH
321Make sure you have MMS (from Digital) or the freeware MMK ( available
322from MadGoat at http://www.madgoat.com ). Then type this to create
323the DESCRIP.MMS for the module:
fb9cefb4
GS
324
325 perl Makefile.PL
326
327Now you're ready to build:
328
fb9cefb4
GS
329 mms test
330
331Substitute C<mmk> for C<mms> above if you're using MMK.
332
333D. INSTALL
334
91826056 335Type
fb9cefb4
GS
336
337 mms install
338
339Substitute C<mmk> for C<mms> above if you're using MMK.
340
341=item *
342
343B<If you're on MVS>,
344
91826056 345Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
fb9cefb4
GS
346ASCII to EBCDIC.
347
91826056 348A. DECOMPRESS
fb9cefb4 349
07698885 350Decompress the file with C<gzip -d yourmodule.tar.gz>
fb9cefb4 351
07698885
RGS
352You can get gzip from
353http://www.s390.ibm.com/products/oe/bpxqp1.html
fb9cefb4
GS
354
355B. UNPACK
356
91826056 357Unpack the result with
fb9cefb4
GS
358
359 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
360
361The BUILD and INSTALL steps are identical to those for Unix. Some
362modules generate Makefiles that work better with GNU make, which is
1577cd80 363available from http://www.mks.com/s390/gnu/
fb9cefb4
GS
364
365=back
366
24dc5443
JH
367=head1 PORTABILITY
368
369Note that not all modules will work with on all platforms.
370See L<perlport> for more information on portability issues.
371Read the documentation to see if the module will work on your
372system. There are basically three categories
373of modules that will not work "out of the box" with all
374platforms (with some possibility of overlap):
375
376=over 4
377
378=item *
379
380B<Those that should, but don't.> These need to be fixed; consider
381contacting the author and possibly writing a patch.
382
383=item *
384
385B<Those that need to be compiled, where the target platform
386doesn't have compilers readily available.> (These modules contain
387F<.xs> or F<.c> files, usually.) You might be able to find
388existing binaries on the CPAN or elsewhere, or you might
389want to try getting compilers and building it yourself, and then
390release the binary for other poor souls to use.
391
392=item *
393
394B<Those that are targeted at a specific platform.>
395(Such as the Win32:: modules.) If the module is targeted
396specifically at a platform other than yours, you're out
397of luck, most likely.
398
399=back
400
401
402
403Check the CPAN Testers if a module should work with your platform
404but it doesn't behave as you'd expect, or you aren't sure whether or
405not a module will work under your platform. If the module you want
406isn't listed there, you can test it yourself and let CPAN Testers know,
407you can join CPAN Testers, or you can request it be tested.
408
409 http://testers.cpan.org/
410
411
fb9cefb4
GS
412=head1 HEY
413
414If you have any suggested changes for this page, let me know. Please
415don't send me mail asking for help on how to install your modules.
416There are too many modules, and too few Orwants, for me to be able to
417answer or even acknowledge all your questions. Contact the module
418author instead, or post to comp.lang.perl.modules, or ask someone
419familiar with Perl on your operating system.
420
421=head1 AUTHOR
422
91826056 423Jon Orwant
fb9cefb4 424
8eabb633 425orwant@medita.mit.edu
fb9cefb4 426
b3539c74
JH
427with invaluable help from Chris Nandor, and valuable help from Brandon
428Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
429Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
430J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
431Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
fb9cefb4 432
b3539c74 433First version July 22, 1998; last revised November 21, 2001.
fb9cefb4
GS
434
435=head1 COPYRIGHT
436
376270a4 437Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
fb9cefb4 438
608704e1 439This document may be distributed under the same terms as Perl itself.