This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fix a small typo in Storable.xs
[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
GS
49"/my/perl_directory/lib/site_perl"> or sometimes just C<use
50"/my/perl_directory">.
fb9cefb4
GS
51
52=over 4
53
54=item *
55
56B<If you're on Unix,>
57
58You can use Andreas Koenig's CPAN module
19799a22
GS
59(which comes standard with Perl, or can itself be downloaded
60from http://www.perl.com/CPAN/modules/by-module/CPAN)
fb9cefb4
GS
61to automate the following steps, from DECOMPRESS through INSTALL.
62
63A. DECOMPRESS
64
65Decompress the file with C<gzip -d yourmodule.tar.gz>
66
67You can get gzip from ftp://prep.ai.mit.edu/pub/gnu.
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
129of the directories you see when you type
130
131 perl -e 'print "@INC"'
132
133=item *
134
135B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
136
137 A. DECOMPRESS
138
139When you download the module, make sure it ends in either
19799a22 140F<.tar.gz> or F<.zip>. Windows browsers sometimes
fb9cefb4
GS
141download C<.tar.gz> files as C<_tar.tar>, because
142early versions of Windows prohibited more than one dot in a filename.
143
19799a22 144You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
fb9cefb4
GS
145decompress and unpack modules.
146
147Or, you can use InfoZip's C<unzip> utility (
6cecdcac
GS
148http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
149C<unzip yourmodule.zip> in your shell.
fb9cefb4
GS
150
151Or, if you have a working C<tar> and C<gzip>, you can
152type
153
154 gzip -cd yourmodule.tar.gz | tar xvf -
155
156in the shell to decompress C<yourmodule.tar.gz>. This will
157UNPACK your module as well.
158
159 B. UNPACK
160
19799a22 161The methods in DECOMPRESS will have done this for you.
fb9cefb4
GS
162
163 C. BUILD
164
165Go into the newly-created directory and type:
166
167 perl Makefile.PL
168 dmake
169 dmake test
170
171Depending on your perl configuration, C<dmake> might not be
172available. You might have to substitute whatever C<perl
173-V:make> says. (Usually, that will be C<nmake> or
174C<make>.)
175
176 D. INSTALL
177
178While still in that directory, type:
179
180 dmake install
181
182=item *
183
184B<If you're using a Macintosh,>
185
186A. DECOMPRESS
187
be94a901
GS
188In general, all Macintosh decompression utilities mentioned here
189can be found in the Info-Mac Hyperarchive
190( http://hyperarchive.lcs.mit.edu/HyperArchive.html ).
4375e838 191Specifically the "Compress & Translate" listing
be94a901
GS
192( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
193
194
19799a22 195You can either use the shareware B<StuffIt Expander> program
6cecdcac 196( http://www.aladdinsys.com/expander/ )
be94a901 197in combination with I<DropStuff with Expander Enhancer>
6cecdcac 198( http://www.aladdinsys.com/dropstuff/ )
19799a22 199or the freeware B<MacGzip> program (
fb9cefb4
GS
200http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
201
be94a901 202
fb9cefb4
GS
203B. UNPACK
204
205If you're using DropStuff or Stuffit, you can just extract the tar
6cecdcac
GS
206archive. Otherwise, you can use the freeware B<suntar> or I<Tar> (
207http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
fb9cefb4
GS
208
209C. BUILD
210
211Does the module require compilation?
212
2131. If it does,
214
215Overview: You need MPW and a combination of new and old CodeWarrior
216compilers for MPW and libraries. Makefiles created for building under
19799a22 217MPW use Metrowerks compilers. It's most likely possible to build
fb9cefb4 218without other compilers, but it has not been done successfully, to our
19799a22 219knowledge. Read the documentation in I<MacPerl: Power and Ease> (
fb9cefb4
GS
220http://www.ptf.com/macperl/ ) on porting/building extensions, or find
221an existing precompiled binary, or hire someone to build it for you.
222
223Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
224to build it for you. To subscribe to the mac-perl mailing list, send
225mail to mac-perl-request@iis.ee.ethz.ch.
226
2272. If the module doesn't require compilation, go to INSTALL.
228
229D. INSTALL
230
231Make sure the newlines for the modules are in Mac format, not Unix format.
be94a901
GS
232If they are not then you might have decompressed them incorrectly. Check
233your decompression and unpacking utilities settings to make sure they are
234translating text files properly.
7711098a 235
19799a22
GS
236As a last resort, you can use the perl one-liner:
237
238 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
7711098a
GS
239
240on the source files.
be94a901 241
fb9cefb4
GS
242Move the files manually into the correct folders.
243
244Move the files to their final destination: This will
245most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
246C<HD:MacPerl folder:site_lib:>). You can add new paths to
247the default C<@INC> in the Preferences menu item in the
248MacPerl application (C<$ENV{MACPERL}site_lib:> is added
249automagically). Create whatever directory structures are required
250(i.e., for C<Some::Module>, create
251C<$ENV{MACPERL}site_lib:Some:> and put
252C<Module.pm> in that directory).
253
254Run the following script (or something like it):
255
256 #!perl -w
257 use AutoSplit;
258 my $dir = "${MACPERL}site_perl";
259 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
260
261Eventually there should be a way to automate the installation process; some
262solutions exist, but none are ready for the general public yet.
263
264=item *
265
266B<If you're on the DJGPP port of DOS,>
267
268 A. DECOMPRESS
269
270djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
271will both uncompress and unpack.
272
273 B. UNPACK
274
275See above.
276
277 C. BUILD
278
279Go into the newly-created directory and type:
280
281 perl Makefile.PL
282 make
283 make test
284
19799a22 285You will need the packages mentioned in F<README.dos>
fb9cefb4
GS
286in the Perl distribution.
287
288 D. INSTALL
289
290While still in that directory, type:
291
292 make install
c47ff5f1 293
19799a22 294You will need the packages mentioned in F<README.dos> in the Perl distribution.
fb9cefb4
GS
295
296=item *
297
298B<If you're on OS/2,>
299
300Get the EMX development suite and gzip/tar, from either Hobbes (
301http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
302the instructions for Unix.
303
304=item *
305
306B<If you're on VMS,>
307
19799a22
GS
308When downloading from CPAN, save your file with a F<.tgz>
309extension instead of F<.tar.gz>. All other periods in the
fb9cefb4
GS
310filename should be replaced with underscores. For example,
311C<Your-Module-1.33.tar.gz> should be downloaded as
312C<Your-Module-1_33.tgz>.
313
314A. DECOMPRESS
315
316Type
317
318 gzip -d Your-Module.tgz
319
320or, for zipped modules, type
321
322 unzip Your-Module.zip
323
324Executables for gzip, zip, and VMStar ( Alphas:
6cecdcac
GS
325http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
326http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
fb9cefb4
GS
327
328gzip and tar
329are also available at ftp://ftp.digital.com/pub/VMS.
330
331Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
332package. The former is a simple compression tool; the latter permits
333creation of multi-file archives.
334
335B. UNPACK
336
337If you're using VMStar:
338
339 VMStar xf Your-Module.tar
340
341Or, if you're fond of VMS command syntax:
342
343 tar/extract/verbose Your_Module.tar
344
345C. BUILD
346
347Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at http://www.madgoat.com ). Then type this to create the
348DESCRIP.MMS for the module:
349
350 perl Makefile.PL
351
352Now you're ready to build:
353
354 mms
355 mms test
356
357Substitute C<mmk> for C<mms> above if you're using MMK.
358
359D. INSTALL
360
361Type
362
363 mms install
364
365Substitute C<mmk> for C<mms> above if you're using MMK.
366
367=item *
368
369B<If you're on MVS>,
370
19799a22 371Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
fb9cefb4
GS
372ASCII to EBCDIC.
373
374A. DECOMPRESS
375
376 Decompress the file with C<gzip -d yourmodule.tar.gz>
377
378 You can get gzip from
379 http://www.s390.ibm.com/products/oe/bpxqp1.html.
380
381B. UNPACK
382
383Unpack the result with
384
385 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
386
387The BUILD and INSTALL steps are identical to those for Unix. Some
388modules generate Makefiles that work better with GNU make, which is
389available from http://www.mks.com/s390/gnu/index.htm.
390
391=back
392
393=head1 HEY
394
395If you have any suggested changes for this page, let me know. Please
396don't send me mail asking for help on how to install your modules.
397There are too many modules, and too few Orwants, for me to be able to
398answer or even acknowledge all your questions. Contact the module
399author instead, or post to comp.lang.perl.modules, or ask someone
400familiar with Perl on your operating system.
401
402=head1 AUTHOR
403
404Jon Orwant
405
406orwant@tpj.com
407
408The Perl Journal, http://tpj.com
409
410with invaluable help from Brandon Allbery, Charles Bailey, Graham
411Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
412Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
413Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
414Sugalski, Larry Virden, and Ilya Zakharevich.
415
416July 22, 1998
417
418=head1 COPYRIGHT
419
420Copyright (C) 1998 Jon Orwant. All Rights Reserved.
421
422Permission is granted to make and distribute verbatim copies of this
423documentation provided the copyright notice and this permission notice are
424preserved on all copies.
425
426Permission is granted to copy and distribute modified versions of this
427documentation under the conditions for verbatim copying, provided also
428that they are marked clearly as modified versions, that the authors'
429names and title are unchanged (though subtitles and additional
430authors' names may be added), and that the entire resulting derived
431work is distributed under the terms of a permission notice identical
432to this one.
433
434Permission is granted to copy and distribute translations of this
435documentation into another language, under the above conditions for
436modified versions.
437