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