This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [PATCH] Porting/genlog -bi and range
[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
a74498e7 13http://www.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
22instance, C<perl -MCGI::Carp -e 1>.
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
48I<not> a substitute for reading the README and INSTALL files that
49might have come with your module!
50
51Also note that these instructions are tailored for installing the
b3539c74 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
56C</my/perl_directory>. Then you can use the modules from your Perl
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
62directory) and use this approach.
fb9cefb4
GS
63
64=over 4
65
66=item *
67
b3539c74 68B<If you're on a Unix or Linux system,>
fb9cefb4 69
b3539c74 70You can use Andreas Koenig's CPAN module
a74498e7 71( http://www.cpan.org/modules/by-module/CPAN )
fb9cefb4
GS
72to automate the following steps, from DECOMPRESS through INSTALL.
73
b3539c74 74A. DECOMPRESS
fb9cefb4
GS
75
76Decompress the file with C<gzip -d yourmodule.tar.gz>
77
b3539c74 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
93 make
94 make test
95
b3539c74
JH
96or
97
98 perl Makefile.PL PREFIX=/my/perl_directory
99
100to install it locally. (Remember that if you do this, you'll have to
101put C<use lib "/my/perl_directory";> near the top of the program that
102is to use this module.
103
fb9cefb4
GS
104D. INSTALL
105
106While still in that directory, type:
107
108 make install
109
b3539c74 110Make sure you have the appropriate permissions to install the module
fb9cefb4
GS
111in your Perl 5 library directory. Often, you'll need to be root.
112
113That's all you need to do on Unix systems with dynamic linking.
b3539c74
JH
114Most Unix systems have dynamic linking -- if yours doesn't, or if for
115another reason you have a statically-linked perl, B<and> the
fb9cefb4
GS
116module requires compilation, you'll need to build a new Perl binary
117that includes the module. Again, you'll probably need to be root.
118
119=item *
120
b3539c74
JH
121B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
122
123First, type C<ppm> from a shell and see whether ActiveState's PPM
124repository has your module. If so, you can install it with C<ppm> and
125you won't have to bother with any of the other steps here. You might
126be able to use the CPAN instructions from the "Unix or Linux" section
127above as well; give it a try. Otherwise, you'll have to follow the
128steps below.
fb9cefb4
GS
129
130 A. DECOMPRESS
131
b3539c74 132You can use the shareware Winzip ( http://www.winzip.com ) to
fb9cefb4
GS
133decompress and unpack modules.
134
135 B. UNPACK
136
137If you used WinZip, this was already done for you.
138
139 C. BUILD
140
b3539c74
JH
141Does the module require compilation (i.e. does it have files that end
142in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it doesn't, go to INSTALL.
143If it does, life is now officially tough for you, because you have to
144compile the module yourself -- no easy feat on Windows. You'll need
145the C<nmake> utility, available at
146ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.
fb9cefb4
GS
147
148 D. INSTALL
149
150Copy the module into your Perl's I<lib> directory. That'll be one
b3539c74 151of the directories you see when you type
fb9cefb4
GS
152
153 perl -e 'print "@INC"'
154
155=item *
156
fb9cefb4
GS
157B<If you're using a Macintosh,>
158
b3539c74 159
fb9cefb4
GS
160A. DECOMPRESS
161
b3539c74
JH
162First, make sure you have the latest B<cpan-mac> distribution (
163http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
164doing all of the steps. Read the cpan-mac directions carefully and
165install it. If you choose not to use cpan-mac for some reason, there
166are alternatives listed here.
be94a901 167
24dc5443
JH
168After installing cpan-mac, drop the module archive on the
169B<untarzipme> droplet, which will decompress and unpack for you.
be94a901 170
24dc5443
JH
171B<Or>, you can either use the shareware B<StuffIt Expander> program
172( http://www.aladdinsys.com/expander/ )
173in combination with B<DropStuff with Expander Enhancer>
174( http://www.aladdinsys.com/dropstuff/ )
19799a22 175or the freeware B<MacGzip> program (
fb9cefb4
GS
176http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
177
178B. UNPACK
179
24dc5443
JH
180If you're using untarzipme or StuffIt, the archive should be extracted
181now. B<Or>, you can use the freeware B<suntar> or I<Tar> (
6cecdcac 182http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
fb9cefb4
GS
183
184C. BUILD
185
24dc5443
JH
186Check the contents of the distribution.
187Read the module's documentation, looking for
188reasons why you might have trouble using it with MacPerl. Look for
189F<.xs> and F<.c> files, which normally denote that the distribution
190must be compiled, and you cannot install it "out of the box."
191(See L<"PORTABILITY">.)
192
193If a module does not work on MacPerl but should, or needs to be
194compiled, see if the module exists already as a port on the
195MacPerl Module Porters site (http://pudge.net/mmp/).
196For more information on doing XS with MacPerl yourself, see
197Arved Sandstrom's XS tutorial (http://macperl.com/depts/Tutorials/),
198and then consider uploading your binary to the CPAN and
199registering it on the MMP site.
fb9cefb4 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
244djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
b3539c74 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
256 make
257 make test
258
b3539c74 259You will need the packages mentioned in C<Readme.dos>
fb9cefb4
GS
260in the Perl distribution.
261
262 D. INSTALL
263
264While still in that directory, type:
265
b3539c74
JH
266 make install
267
268You will need the packages mentioned in Readme.dos in the Perl distribution.
fb9cefb4
GS
269
270=item *
271
272B<If you're on OS/2,>
273
274Get the EMX development suite and gzip/tar, from either Hobbes (
275http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
276the instructions for Unix.
277
278=item *
279
280B<If you're on VMS,>
281
b3539c74
JH
282When downloading from CPAN, save your file with a C<.tgz>
283extension instead of C<.tar.gz>. All other periods in the
fb9cefb4
GS
284filename should be replaced with underscores. For example,
285C<Your-Module-1.33.tar.gz> should be downloaded as
286C<Your-Module-1_33.tgz>.
287
288A. DECOMPRESS
289
b3539c74 290Type
fb9cefb4
GS
291
292 gzip -d Your-Module.tgz
293
b3539c74 294or, for zipped modules, type
fb9cefb4
GS
295
296 unzip Your-Module.zip
297
298Executables for gzip, zip, and VMStar ( Alphas:
b3539c74
JH
299http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
300http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).
fb9cefb4
GS
301
302gzip and tar
303are also available at ftp://ftp.digital.com/pub/VMS.
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
b3539c74 319C. BUILD
fb9cefb4 320
b3539c74
JH
321Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at http://www.madgoat.com ). Then type this to create the
322DESCRIP.MMS for the module:
fb9cefb4
GS
323
324 perl Makefile.PL
325
326Now you're ready to build:
327
328 mms
329 mms test
330
331Substitute C<mmk> for C<mms> above if you're using MMK.
332
333D. INSTALL
334
b3539c74 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
b3539c74 345Introduce the .tar.gz file into an HFS as binary; don't translate from
fb9cefb4
GS
346ASCII to EBCDIC.
347
b3539c74 348A. DECOMPRESS
fb9cefb4
GS
349
350 Decompress the file with C<gzip -d yourmodule.tar.gz>
351
b3539c74 352 You can get gzip from
fb9cefb4
GS
353 http://www.s390.ibm.com/products/oe/bpxqp1.html.
354
355B. UNPACK
356
b3539c74 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
363available from http://www.mks.com/s390/gnu/index.htm.
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
b3539c74 423Jon Orwant
fb9cefb4
GS
424
425orwant@tpj.com
426
427The Perl Journal, http://tpj.com
428
b3539c74
JH
429with invaluable help from Chris Nandor, and valuable help from Brandon
430Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
431Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
432J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
433Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
fb9cefb4 434
b3539c74 435First version July 22, 1998; last revised November 21, 2001.
fb9cefb4
GS
436
437=head1 COPYRIGHT
438
b3539c74 439Copyright (C) 1998, 2001 Jon Orwant. All Rights Reserved.
fb9cefb4
GS
440
441Permission is granted to make and distribute verbatim copies of this
442documentation provided the copyright notice and this permission notice are
443preserved on all copies.
444
445Permission is granted to copy and distribute modified versions of this
446documentation under the conditions for verbatim copying, provided also
447that they are marked clearly as modified versions, that the authors'
448names and title are unchanged (though subtitles and additional
449authors' names may be added), and that the entire resulting derived
450work is distributed under the terms of a permission notice identical
451to this one.
452
453Permission is granted to copy and distribute translations of this
454documentation into another language, under the above conditions for
455modified versions.
b3539c74 456