This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move more URLs from http:// to https://
[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
71c89d21 10as a Perl developer at L<https://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
71c89d21 13L<https://www.cpan.org/> , and searched at L<https://metacpan.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
6c1c521a 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
ac036724 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
f703fc96 56F</my/perl_directory>. Then you can use the modules from your Perl
b3539c74
JH
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
8e30f651 68B<If you're on a Unix or Unix-like system,>
fb9cefb4 69
91826056 70You can use Andreas Koenig's CPAN module
4b05bc8e 71( L<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
4b05bc8e 78You can get gzip from L<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
fb9cefb4
GS
93 make test
94
91826056 95or
b3539c74
JH
96
97 perl Makefile.PL PREFIX=/my/perl_directory
98
99to install it locally. (Remember that if you do this, you'll have to
100put C<use lib "/my/perl_directory";> near the top of the program that
101is to use this module.
102
fb9cefb4
GS
103D. INSTALL
104
105While still in that directory, type:
106
107 make install
108
b3539c74 109Make sure you have the appropriate permissions to install the module
fb9cefb4
GS
110in your Perl 5 library directory. Often, you'll need to be root.
111
112That's all you need to do on Unix systems with dynamic linking.
ac036724 113Most Unix systems have dynamic linking. If yours doesn't, or if for
b3539c74 114another reason you have a statically-linked perl, B<and> the
fb9cefb4
GS
115module requires compilation, you'll need to build a new Perl binary
116that includes the module. Again, you'll probably need to be root.
117
118=item *
119
f321be7e 120B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),>
b3539c74
JH
121
122First, type C<ppm> from a shell and see whether ActiveState's PPM
123repository has your module. If so, you can install it with C<ppm> and
124you won't have to bother with any of the other steps here. You might
125be able to use the CPAN instructions from the "Unix or Linux" section
126above as well; give it a try. Otherwise, you'll have to follow the
127steps below.
fb9cefb4
GS
128
129 A. DECOMPRESS
130
4b05bc8e 131You can use the shareware Winzip ( L<http://www.winzip.com> ) to
fb9cefb4
GS
132decompress and unpack modules.
133
134 B. UNPACK
135
136If you used WinZip, this was already done for you.
137
138 C. BUILD
139
376270a4 140You'll need the C<nmake> utility, available at
4b05bc8e 141L<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe>
376270a4 142or dmake, available on CPAN.
71c89d21 143L<https://search.cpan.org/dist/dmake/>
376270a4
MS
144
145Does the module require compilation (i.e. does it have files that end
146in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
147officially tough for you, because you have to compile the module
ac036724 148yourself (no easy feat on Windows). You'll need a compiler such as
376270a4
MS
149Visual C++. Alternatively, you can download a pre-built PPM package
150from ActiveState.
4b05bc8e 151L<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
376270a4
MS
152
153Go into the newly-created directory and type:
154
155 perl Makefile.PL
156 nmake test
157
fb9cefb4
GS
158
159 D. INSTALL
160
376270a4 161While still in that directory, type:
fb9cefb4 162
376270a4 163 nmake install
fb9cefb4
GS
164
165=item *
166
fb9cefb4
GS
167B<If you're on the DJGPP port of DOS,>
168
169 A. DECOMPRESS
170
4b05bc8e 171djtarx ( L<ftp://ftp.delorie.com/pub/djgpp/current/v2/> )
91826056 172will both uncompress and unpack.
fb9cefb4
GS
173
174 B. UNPACK
175
176See above.
177
178 C. BUILD
179
180Go into the newly-created directory and type:
181
182 perl Makefile.PL
fb9cefb4
GS
183 make test
184
91826056 185You will need the packages mentioned in F<README.dos>
fb9cefb4
GS
186in the Perl distribution.
187
188 D. INSTALL
189
190While still in that directory, type:
191
b3539c74 192 make install
91826056
JH
193
194You will need the packages mentioned in F<README.dos> in the Perl distribution.
fb9cefb4
GS
195
196=item *
197
198B<If you're on OS/2,>
199
200Get the EMX development suite and gzip/tar, from either Hobbes (
4b05bc8e 201L<http://hobbes.nmsu.edu> ) or Leo ( L<http://www.leo.org> ), and then follow
fb9cefb4
GS
202the instructions for Unix.
203
204=item *
205
206B<If you're on VMS,>
207
b3539c74
JH
208When downloading from CPAN, save your file with a C<.tgz>
209extension instead of C<.tar.gz>. All other periods in the
fb9cefb4
GS
210filename should be replaced with underscores. For example,
211C<Your-Module-1.33.tar.gz> should be downloaded as
212C<Your-Module-1_33.tgz>.
213
214A. DECOMPRESS
215
91826056 216Type
fb9cefb4
GS
217
218 gzip -d Your-Module.tgz
219
91826056 220or, for zipped modules, type
fb9cefb4
GS
221
222 unzip Your-Module.zip
223
91826056
JH
224Executables for gzip, zip, and VMStar:
225
05e8c65e 226 http://www.hp.com/go/openvms/freeware/
fb9cefb4 227
91826056
JH
228and their source code:
229
230 http://www.fsf.org/order/ftp.html
fb9cefb4
GS
231
232Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
233package. The former is a simple compression tool; the latter permits
234creation of multi-file archives.
235
236B. UNPACK
237
238If you're using VMStar:
239
240 VMStar xf Your-Module.tar
241
242Or, if you're fond of VMS command syntax:
243
244 tar/extract/verbose Your_Module.tar
245
91826056 246C. BUILD
fb9cefb4 247
91826056 248Make sure you have MMS (from Digital) or the freeware MMK ( available
4b05bc8e 249from MadGoat at L<http://www.madgoat.com> ). Then type this to create
91826056 250the DESCRIP.MMS for the module:
fb9cefb4
GS
251
252 perl Makefile.PL
253
254Now you're ready to build:
255
fb9cefb4
GS
256 mms test
257
258Substitute C<mmk> for C<mms> above if you're using MMK.
259
260D. INSTALL
261
91826056 262Type
fb9cefb4
GS
263
264 mms install
265
266Substitute C<mmk> for C<mms> above if you're using MMK.
267
268=item *
269
270B<If you're on MVS>,
271
91826056 272Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
fb9cefb4
GS
273ASCII to EBCDIC.
274
91826056 275A. DECOMPRESS
fb9cefb4 276
07698885 277Decompress the file with C<gzip -d yourmodule.tar.gz>
fb9cefb4 278
07698885 279You can get gzip from
4b05bc8e 280L<http://www.s390.ibm.com/products/oe/bpxqp1.html>
fb9cefb4
GS
281
282B. UNPACK
283
91826056 284Unpack the result with
fb9cefb4
GS
285
286 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
287
288The BUILD and INSTALL steps are identical to those for Unix. Some
289modules generate Makefiles that work better with GNU make, which is
4b05bc8e 290available from L<http://www.mks.com/s390/gnu/>
fb9cefb4
GS
291
292=back
293
24dc5443
JH
294=head1 PORTABILITY
295
296Note that not all modules will work with on all platforms.
297See L<perlport> for more information on portability issues.
298Read the documentation to see if the module will work on your
299system. There are basically three categories
300of modules that will not work "out of the box" with all
301platforms (with some possibility of overlap):
302
303=over 4
304
305=item *
306
307B<Those that should, but don't.> These need to be fixed; consider
308contacting the author and possibly writing a patch.
309
310=item *
311
312B<Those that need to be compiled, where the target platform
313doesn't have compilers readily available.> (These modules contain
314F<.xs> or F<.c> files, usually.) You might be able to find
315existing binaries on the CPAN or elsewhere, or you might
316want to try getting compilers and building it yourself, and then
317release the binary for other poor souls to use.
318
319=item *
320
321B<Those that are targeted at a specific platform.>
322(Such as the Win32:: modules.) If the module is targeted
323specifically at a platform other than yours, you're out
324of luck, most likely.
325
326=back
327
328
329
330Check the CPAN Testers if a module should work with your platform
331but it doesn't behave as you'd expect, or you aren't sure whether or
332not a module will work under your platform. If the module you want
333isn't listed there, you can test it yourself and let CPAN Testers know,
334you can join CPAN Testers, or you can request it be tested.
335
71c89d21 336 https://cpantesters.org/
24dc5443
JH
337
338
fb9cefb4
GS
339=head1 HEY
340
341If you have any suggested changes for this page, let me know. Please
342don't send me mail asking for help on how to install your modules.
343There are too many modules, and too few Orwants, for me to be able to
344answer or even acknowledge all your questions. Contact the module
32356571 345author instead, ask someone familiar with Perl on your operating
71c89d21 346system, or if all else fails, file a ticket at L<https://rt.cpan.org/>.
fb9cefb4
GS
347
348=head1 AUTHOR
349
91826056 350Jon Orwant
fb9cefb4 351
8eabb633 352orwant@medita.mit.edu
fb9cefb4 353
b3539c74
JH
354with invaluable help from Chris Nandor, and valuable help from Brandon
355Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
356Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
357J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
358Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
fb9cefb4 359
b3539c74 360First version July 22, 1998; last revised November 21, 2001.
fb9cefb4
GS
361
362=head1 COPYRIGHT
363
376270a4 364Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
fb9cefb4 365
608704e1 366This document may be distributed under the same terms as Perl itself.