This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Mac and other portability updates from Chris Nandor.
[perl5.git] / pod / perlmodinstall.pod
1 =head1 NAME
2
3 perlmodinstall - Installing CPAN Modules
4
5 =head1 DESCRIPTION
6
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 .
16
17 This documentation is for people who want to download CPAN modules
18 and install them on their own computer.
19
20 =head2 PREAMBLE
21
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
24 steps:
25
26 =over 5
27
28 =item B<DECOMPRESS> the file
29
30 =item B<UNPACK> the file into a directory
31
32 =item B<BUILD> the module (sometimes unnecessary)
33
34 =item B<INSTALL> the module.
35
36 =back
37
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!
41
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">.
51
52 =over 4
53
54 =item *
55
56 B<If you're on Unix,>
57
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.
62
63 A. DECOMPRESS
64
65 Decompress the file with C<gzip -d yourmodule.tar.gz>
66
67 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
68
69 Or, you can combine this step with the next to save disk space:
70
71      gzip -dc yourmodule.tar.gz | tar -xof -
72
73 B. UNPACK
74
75 Unpack the result with C<tar -xof yourmodule.tar>
76
77 C. BUILD
78
79 Go into the newly-created directory and type:
80
81       perl Makefile.PL
82       make
83       make test
84
85 D. INSTALL
86
87 While still in that directory, type:
88
89       make install
90
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.
93
94 Perl maintains a record of all module installations.  To look at
95 this list, simply type:
96
97       perldoc perllocal
98
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.
104
105 =item *
106
107 B<If you're running Windows 95 or NT with the ActiveState port of Perl>
108
109    A. DECOMPRESS
110
111 You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
112 decompress and unpack modules.
113
114    B. UNPACK
115
116 If you used WinZip, this was already done for you.
117
118    C. BUILD
119
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.
125
126    D. INSTALL
127
128 Copy the module into your Perl's I<lib> directory.  That'll be one
129 of the directories you see when you type
130
131    perl -e 'print "@INC"'
132
133 =item *
134
135 B<If you're running Windows 95 or NT with the core Windows distribution of
136 Perl,>
137
138    A. DECOMPRESS
139
140 When you download the module, make sure it ends in either
141 F<.tar.gz> or F<.zip>.  Windows browsers sometimes
142 download C<.tar.gz> files as C<_tar.tar>, because
143 early versions of Windows prohibited more than one dot in a filename.
144
145 You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
146 decompress and unpack modules.
147
148 Or, you can use InfoZip's C<unzip> utility (
149 http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
150 C<unzip yourmodule.zip> in your shell.
151
152 Or, if you have a working C<tar> and C<gzip>, you can
153 type
154
155    gzip -cd yourmodule.tar.gz | tar xvf -
156
157 in the shell to decompress C<yourmodule.tar.gz>.  This will
158 UNPACK your module as well.
159
160    B. UNPACK
161
162 The methods in DECOMPRESS will have done this for you.
163
164    C. BUILD
165
166 Go into the newly-created directory and type:
167
168       perl Makefile.PL
169       dmake
170       dmake test
171
172 Depending on your perl configuration, C<dmake> might not be
173 available.  You might have to substitute whatever C<perl
174 -V:make> says. (Usually, that will be C<nmake> or
175 C<make>.)
176
177    D. INSTALL
178
179 While still in that directory, type:
180
181       dmake install
182
183 =item *
184
185 B<If you're using a Macintosh,>
186
187 A. DECOMPRESS
188
189 First thing you should do is make sure you have the latest B<cpan-mac>
190 distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has
191 utilities for doing all of the steps.  Read the cpan-mac directions
192 carefully and install it.  If you choose not to use cpan-mac
193 for some reason, there are alternatives listed here.
194
195 After installing cpan-mac, drop the module archive on the
196 B<untarzipme> droplet, which will decompress and unpack for you.
197
198 B<Or>, you can either use the shareware B<StuffIt Expander> program
199 ( http://www.aladdinsys.com/expander/ )
200 in combination with B<DropStuff with Expander Enhancer>
201 ( http://www.aladdinsys.com/dropstuff/ )
202 or the freeware B<MacGzip> program (
203 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
204
205 B. UNPACK
206
207 If you're using untarzipme or StuffIt, the archive should be extracted
208 now.  B<Or>, you can use the freeware B<suntar> or I<Tar> (
209 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
210
211 C. BUILD
212
213 Check the contents of the distribution.
214 Read the module's documentation, looking for
215 reasons why you might have trouble using it with MacPerl.  Look for
216 F<.xs> and F<.c> files, which normally denote that the distribution
217 must be compiled, and you cannot install it "out of the box."
218 (See L<"PORTABILITY">.)
219
220 If a module does not work on MacPerl but should, or needs to be
221 compiled, see if the module exists already as a port on the
222 MacPerl Module Porters site (http://pudge.net/mmp/).
223 For more information on doing XS with MacPerl yourself, see
224 Arved Sandstrom's XS tutorial (http://macperl.com/depts/Tutorials/),
225 and then consider uploading your binary to the CPAN and
226 registering it on the MMP site.
227
228 D. INSTALL
229
230 If you are using cpan-mac, just drop the folder on the
231 B<installme> droplet, and use the module.
232
233 B<Or>, if you aren't using cpan-mac, do some manual labor.
234
235 Make sure the newlines for the modules are in Mac format, not Unix format.
236 If they are not then you might have decompressed them incorrectly.  Check
237 your decompression and unpacking utilities settings to make sure they are
238 translating text files properly.
239
240 As a last resort, you can use the perl one-liner:
241
242     perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
243
244 on the source files.
245
246 Then move the files (probably just the F<.pm> files, though there
247 may be some additional ones, too; check the module documentation)
248 to their final destination: This will
249 most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
250 C<HD:MacPerl folder:site_lib:>).  You can add new paths to
251 the default C<@INC> in the Preferences menu item in the
252 MacPerl application (C<$ENV{MACPERL}site_lib:> is added
253 automagically).  Create whatever directory structures are required
254 (i.e., for C<Some::Module>, create
255 C<$ENV{MACPERL}site_lib:Some:> and put
256 C<Module.pm> in that directory).
257
258 Then run the following script (or something like it):
259
260      #!perl -w
261      use AutoSplit;
262      my $dir = "${MACPERL}site_perl";
263      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
264
265 =item *
266
267 B<If you're on the DJGPP port of DOS,>
268
269    A. DECOMPRESS
270
271 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
272 will both uncompress and unpack.
273
274    B. UNPACK
275
276 See above.
277
278    C. BUILD
279
280 Go into the newly-created directory and type:
281
282       perl Makefile.PL
283       make
284       make test
285
286 You will need the packages mentioned in F<README.dos>
287 in the Perl distribution.
288
289    D. INSTALL
290
291 While still in that directory, type:
292
293      make install
294
295 You will need the packages mentioned in F<README.dos> in the Perl distribution.
296
297 =item *
298
299 B<If you're on OS/2,>
300
301 Get the EMX development suite and gzip/tar, from either Hobbes (
302 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
303 the instructions for Unix.
304
305 =item *
306
307 B<If you're on VMS,>
308
309 When downloading from CPAN, save your file with a F<.tgz>
310 extension instead of F<.tar.gz>.  All other periods in the
311 filename should be replaced with underscores.  For example,
312 C<Your-Module-1.33.tar.gz> should be downloaded as
313 C<Your-Module-1_33.tgz>.
314
315 A. DECOMPRESS
316
317 Type
318
319     gzip -d Your-Module.tgz
320
321 or, for zipped modules, type
322
323     unzip Your-Module.zip
324
325 Executables for gzip, zip, and VMStar ( Alphas:
326 http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
327 http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
328
329 gzip and tar
330 are also available at ftp://ftp.digital.com/pub/VMS.
331
332 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
333 package.  The former is a simple compression tool; the latter permits
334 creation of multi-file archives.
335
336 B. UNPACK
337
338 If you're using VMStar:
339
340      VMStar xf Your-Module.tar
341
342 Or, if you're fond of VMS command syntax:
343
344      tar/extract/verbose Your_Module.tar
345
346 C. BUILD
347
348 Make sure you have MMS (from Digital) or the freeware MMK ( available from
349 MadGoat at  http://www.madgoat.com ).  Then type this to create the
350 DESCRIP.MMS for the module:
351
352     perl Makefile.PL
353
354 Now you're ready to build:
355
356     mms
357     mms test
358
359 Substitute C<mmk> for C<mms> above if you're using MMK.
360
361 D. INSTALL
362
363 Type
364
365     mms install
366
367 Substitute C<mmk> for C<mms> above if you're using MMK.
368
369 =item *
370
371 B<If you're on MVS>,
372
373 Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
374 ASCII to EBCDIC.
375
376 A. DECOMPRESS
377
378       Decompress the file with C<gzip -d yourmodule.tar.gz>
379
380       You can get gzip from
381       http://www.s390.ibm.com/products/oe/bpxqp1.html.
382
383 B. UNPACK
384
385 Unpack the result with
386
387      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
388
389 The BUILD and INSTALL steps are identical to those for Unix.  Some
390 modules generate Makefiles that work better with GNU make, which is
391 available from http://www.mks.com/s390/gnu/index.htm.
392
393 =back
394
395
396 =head1 PORTABILITY
397
398 Note that not all modules will work with on all platforms.
399 See L<perlport> for more information on portability issues.
400 Read the documentation to see if the module will work on your
401 system.  There are basically three categories
402 of modules that will not work "out of the box" with all
403 platforms (with some possibility of overlap):
404
405 =over 4
406
407 =item *
408
409 B<Those that should, but don't.>  These need to be fixed; consider
410 contacting the author and possibly writing a patch.
411
412 =item *
413
414 B<Those that need to be compiled, where the target platform
415 doesn't have compilers readily available.>  (These modules contain
416 F<.xs> or F<.c> files, usually.)  You might be able to find
417 existing binaries on the CPAN or elsewhere, or you might
418 want to try getting compilers and building it yourself, and then
419 release the binary for other poor souls to use.
420
421 =item *
422
423 B<Those that are targeted at a specific platform.>
424 (Such as the Win32:: modules.)  If the module is targeted
425 specifically at a platform other than yours, you're out
426 of luck, most likely.
427
428 =back
429
430
431
432 Check the CPAN Testers if a module should work with your platform
433 but it doesn't behave as you'd expect, or you aren't sure whether or
434 not a module will work under your platform.  If the module you want
435 isn't listed there, you can test it yourself and let CPAN Testers know,
436 you can join CPAN Testers, or you can request it be tested.
437
438     http://testers.cpan.org/
439
440
441 =head1 HEY
442
443 If you have any suggested changes for this page, let me know.  Please
444 don't send me mail asking for help on how to install your modules.
445 There are too many modules, and too few Orwants, for me to be able to
446 answer or even acknowledge all your questions.  Contact the module
447 author instead, or post to comp.lang.perl.modules, or ask someone
448 familiar with Perl on your operating system.
449
450 =head1 AUTHOR
451
452 Jon Orwant
453
454 orwant@tpj.com
455
456 The Perl Journal, http://tpj.com
457
458 with invaluable help from Brandon Allbery, Charles Bailey, Graham
459 Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
460 Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
461 Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
462 Sugalski, Larry Virden, and Ilya Zakharevich.
463
464 First version July 22, 1998
465
466 Last Modified August 22, 2000
467
468 =head1 COPYRIGHT
469
470 Copyright (C) 1998, 2000 Jon Orwant.  All Rights Reserved.
471
472 Permission is granted to make and distribute verbatim copies of this
473 documentation provided the copyright notice and this permission notice are
474 preserved on all copies.
475
476 Permission is granted to copy and distribute modified versions of this
477 documentation under the conditions for verbatim copying, provided also
478 that they are marked clearly as modified versions, that the authors'
479 names and title are unchanged (though subtitles and additional
480 authors' names may be added), and that the entire resulting derived
481 work is distributed under the terms of a permission notice identical
482 to this one.
483
484 Permission is granted to copy and distribute translations of this
485 documentation into another language, under the above conditions for
486 modified versions.