This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Reintroduce the U_32-ification to pad.c,
[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
91826056 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
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
91826056 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
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
93 make
94 make test
95
91826056 96or
b3539c74
JH
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
1577cd80 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
91826056 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
1577cd80 195MacPerl Module Porters site ( http://pudge.net/mmp/ ).
24dc5443 196For more information on doing XS with MacPerl yourself, see
1577cd80 197Arved Sandstrom's XS tutorial ( http://macperl.com/depts/Tutorials/ ),
24dc5443
JH
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/ )
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
256 make
257 make test
258
91826056 259You will need the packages mentioned in F<README.dos>
fb9cefb4
GS
260in the Perl distribution.
261
262 D. INSTALL
263
264While still in that directory, type:
265
b3539c74 266 make install
91826056
JH
267
268You will need the packages mentioned in F<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
91826056 290Type
fb9cefb4
GS
291
292 gzip -d Your-Module.tgz
293
91826056 294or, for zipped modules, type
fb9cefb4
GS
295
296 unzip Your-Module.zip
297
91826056
JH
298Executables for gzip, zip, and VMStar:
299
300 http://www.openvms.digital.com/freeware/
301 http://www.crinoid.com/utils/
fb9cefb4 302
91826056
JH
303and their source code:
304
305 http://www.fsf.org/order/ftp.html
fb9cefb4
GS
306
307Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
308package. The former is a simple compression tool; the latter permits
309creation of multi-file archives.
310
311B. UNPACK
312
313If you're using VMStar:
314
315 VMStar xf Your-Module.tar
316
317Or, if you're fond of VMS command syntax:
318
319 tar/extract/verbose Your_Module.tar
320
91826056 321C. BUILD
fb9cefb4 322
91826056
JH
323Make sure you have MMS (from Digital) or the freeware MMK ( available
324from MadGoat at http://www.madgoat.com ). Then type this to create
325the DESCRIP.MMS for the module:
fb9cefb4
GS
326
327 perl Makefile.PL
328
329Now you're ready to build:
330
331 mms
332 mms test
333
334Substitute C<mmk> for C<mms> above if you're using MMK.
335
336D. INSTALL
337
91826056 338Type
fb9cefb4
GS
339
340 mms install
341
342Substitute C<mmk> for C<mms> above if you're using MMK.
343
344=item *
345
346B<If you're on MVS>,
347
91826056 348Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
fb9cefb4
GS
349ASCII to EBCDIC.
350
91826056 351A. DECOMPRESS
fb9cefb4 352
07698885 353Decompress the file with C<gzip -d yourmodule.tar.gz>
fb9cefb4 354
07698885
RGS
355You can get gzip from
356http://www.s390.ibm.com/products/oe/bpxqp1.html
fb9cefb4
GS
357
358B. UNPACK
359
91826056 360Unpack the result with
fb9cefb4
GS
361
362 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
363
364The BUILD and INSTALL steps are identical to those for Unix. Some
365modules generate Makefiles that work better with GNU make, which is
1577cd80 366available from http://www.mks.com/s390/gnu/
fb9cefb4
GS
367
368=back
369
24dc5443
JH
370=head1 PORTABILITY
371
372Note that not all modules will work with on all platforms.
373See L<perlport> for more information on portability issues.
374Read the documentation to see if the module will work on your
375system. There are basically three categories
376of modules that will not work "out of the box" with all
377platforms (with some possibility of overlap):
378
379=over 4
380
381=item *
382
383B<Those that should, but don't.> These need to be fixed; consider
384contacting the author and possibly writing a patch.
385
386=item *
387
388B<Those that need to be compiled, where the target platform
389doesn't have compilers readily available.> (These modules contain
390F<.xs> or F<.c> files, usually.) You might be able to find
391existing binaries on the CPAN or elsewhere, or you might
392want to try getting compilers and building it yourself, and then
393release the binary for other poor souls to use.
394
395=item *
396
397B<Those that are targeted at a specific platform.>
398(Such as the Win32:: modules.) If the module is targeted
399specifically at a platform other than yours, you're out
400of luck, most likely.
401
402=back
403
404
405
406Check the CPAN Testers if a module should work with your platform
407but it doesn't behave as you'd expect, or you aren't sure whether or
408not a module will work under your platform. If the module you want
409isn't listed there, you can test it yourself and let CPAN Testers know,
410you can join CPAN Testers, or you can request it be tested.
411
412 http://testers.cpan.org/
413
414
fb9cefb4
GS
415=head1 HEY
416
417If you have any suggested changes for this page, let me know. Please
418don't send me mail asking for help on how to install your modules.
419There are too many modules, and too few Orwants, for me to be able to
420answer or even acknowledge all your questions. Contact the module
421author instead, or post to comp.lang.perl.modules, or ask someone
422familiar with Perl on your operating system.
423
424=head1 AUTHOR
425
91826056 426Jon Orwant
fb9cefb4
GS
427
428orwant@tpj.com
429
430The Perl Journal, http://tpj.com
431
b3539c74
JH
432with invaluable help from Chris Nandor, and valuable help from Brandon
433Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
434Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
435J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
436Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
fb9cefb4 437
b3539c74 438First version July 22, 1998; last revised November 21, 2001.
fb9cefb4
GS
439
440=head1 COPYRIGHT
441
be3c0a43 442Copyright (C) 1998, 2002 Jon Orwant. All Rights Reserved.
fb9cefb4
GS
443
444Permission is granted to make and distribute verbatim copies of this
445documentation provided the copyright notice and this permission notice are
446preserved on all copies.
447
448Permission is granted to copy and distribute modified versions of this
449documentation under the conditions for verbatim copying, provided also
450that they are marked clearly as modified versions, that the authors'
451names and title are unchanged (though subtitles and additional
452authors' names may be added), and that the entire resulting derived
453work is distributed under the terms of a permission notice identical
454to this one.
455
456Permission is granted to copy and distribute translations of this
457documentation into another language, under the above conditions for
458modified versions.
b3539c74 459