1PERLMODINSTALL(1)      Perl Programmers Reference Guide      PERLMODINSTALL(1)
2
3
4

NAME

6       perlmodinstall - Installing CPAN Modules
7

DESCRIPTION

9       You can think of a module as the fundamental unit of reusable Perl
10       code; see perlmod for details.  Whenever anyone creates a chunk of Perl
11       code that they think will be useful to the world, they register as a
12       Perl developer at <https://www.cpan.org/modules/04pause.html> so that
13       they can then upload their code to the CPAN.  The CPAN is the
14       Comprehensive Perl Archive Network and can be accessed at
15       <https://www.cpan.org/> , and searched at <https://metacpan.org/> .
16
17       This documentation is for people who want to download CPAN modules and
18       install them on their own computer.
19
20   PREAMBLE
21       First, are you sure that the module isn't already on your system?  Try
22       "perl -MFoo -e 1".  (Replace "Foo" with the name of the module; for
23       instance, "perl -MCGI::Carp -e 1".)
24
25       If you don't see an error message, you have the module.  (If you do see
26       an error message, it's still possible you have the module, but that
27       it's not in your path, which you can display with "perl -e "print
28       qq(@INC)"".)  For the remainder of this document, we'll assume that you
29       really honestly truly lack an installed module, but have found it on
30       the CPAN.
31
32       So now you have a file ending in .tar.gz (or, less often, .zip).  You
33       know there's a tasty module inside.  There are four steps you must now
34       take:
35
36       DECOMPRESS the file
37       UNPACK the file into a directory
38       BUILD the module (sometimes unnecessary)
39       INSTALL the module.
40
41       Here's how to perform each step for each operating system.  This is
42       <not> a substitute for reading the README and INSTALL files that might
43       have come with your module!
44
45       Also note that these instructions are tailored for installing the
46       module into your system's repository of Perl modules, but you can
47       install modules into any directory you wish.  For instance, where I say
48       "perl Makefile.PL", you can substitute "perl Makefile.PL
49       PREFIX=/my/perl_directory" to install the modules into
50       /my/perl_directory.  Then you can use the modules from your Perl
51       programs with "use lib "/my/perl_directory/lib/site_perl";" or
52       sometimes just "use "/my/perl_directory";".  If you're on a system that
53       requires superuser/root access to install modules into the directories
54       you see when you type "perl -e "print qq(@INC)"", you'll want to
55       install them into a local directory (such as your home directory) and
56       use this approach.
57
58If you're on a Unix or Unix-like system,
59
60           You can use Andreas Koenig's CPAN module (
61           <https://metacpan.org/release/CPAN> ) to automate the following
62           steps, from DECOMPRESS through INSTALL.
63
64           A. DECOMPRESS
65
66           Decompress the file with "gzip -d yourmodule.tar.gz"
67
68           You can get gzip from <ftp://prep.ai.mit.edu/pub/gnu/>
69
70           Or, you can combine this step with the next to save disk space:
71
72                gzip -dc yourmodule.tar.gz | tar -xof -
73
74           B. UNPACK
75
76           Unpack the result with "tar -xof yourmodule.tar"
77
78           C. BUILD
79
80           Go into the newly-created directory and type:
81
82                 perl Makefile.PL
83                 make test
84
85           or
86
87                 perl Makefile.PL PREFIX=/my/perl_directory
88
89           to install it locally.  (Remember that if you do this, you'll have
90           to put "use lib "/my/perl_directory";" near the top of the program
91           that is to use this module.
92
93           D. INSTALL
94
95           While still in that directory, type:
96
97                 make install
98
99           Make sure you have the appropriate permissions to install the
100           module in your Perl 5 library directory.  Often, you'll need to be
101           root.
102
103           That's all you need to do on Unix systems with dynamic linking.
104           Most Unix systems have dynamic linking. If yours doesn't, or if for
105           another reason you have a statically-linked perl, and the module
106           requires compilation, you'll need to build a new Perl binary that
107           includes the module.  Again, you'll probably need to be root.
108
109If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),
110
111           First, type "ppm" from a shell and see whether ActiveState's PPM
112           repository has your module.  If so, you can install it with "ppm"
113           and you won't have to bother with any of the other steps here.  You
114           might be able to use the CPAN instructions from the "Unix or Linux"
115           section above as well; give it a try.  Otherwise, you'll have to
116           follow the steps below.
117
118              A. DECOMPRESS
119
120           You can use the open source 7-zip ( <https://www.7-zip.org/> ) or
121           the shareware Winzip ( <https://www.winzip.com> ) to decompress and
122           unpack modules.
123
124              B. UNPACK
125
126           If you used WinZip, this was already done for you.
127
128              C. BUILD
129
130           You'll need either "nmake" or "gmake".
131
132           Does the module require compilation (i.e. does it have files that
133           end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, life is now
134           officially tough for you, because you have to compile the module
135           yourself (no easy feat on Windows).  You'll need a compiler such as
136           Visual C++.  Alternatively, you can download a pre-built PPM
137           package from ActiveState.
138           <http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
139
140           Go into the newly-created directory and type:
141
142                 perl Makefile.PL
143                 nmake test
144
145
146              D. INSTALL
147
148           While still in that directory, type:
149
150                 nmake install
151
152If you're on the DJGPP port of DOS,
153
154              A. DECOMPRESS
155
156           djtarx ( <ftp://ftp.delorie.com/pub/djgpp/current/v2/> ) will both
157           uncompress and unpack.
158
159              B. UNPACK
160
161           See above.
162
163              C. BUILD
164
165           Go into the newly-created directory and type:
166
167                 perl Makefile.PL
168                 make test
169
170           You will need the packages mentioned in README.dos in the Perl
171           distribution.
172
173              D. INSTALL
174
175           While still in that directory, type:
176
177                make install
178
179           You will need the packages mentioned in README.dos in the Perl
180           distribution.
181
182If you're on OS/2,
183
184           Get the EMX development suite and gzip/tar from Hobbes (
185           <http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d> ),
186           and then follow the instructions for Unix.
187
188If you're on VMS,
189
190           When downloading from CPAN, save your file with a ".tgz" extension
191           instead of ".tar.gz".  All other periods in the filename should be
192           replaced with underscores.  For example, "Your-Module-1.33.tar.gz"
193           should be downloaded as "Your-Module-1_33.tgz".
194
195           A. DECOMPRESS
196
197           Type
198
199               gzip -d Your-Module.tgz
200
201           or, for zipped modules, type
202
203               unzip Your-Module.zip
204
205           Executables for gzip, zip, and VMStar:
206
207               http://www.hp.com/go/openvms/freeware/
208
209           and their source code:
210
211               http://www.fsf.org/order/ftp.html
212
213           Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
214           package.  The former is a simple compression tool; the latter
215           permits creation of multi-file archives.
216
217           B. UNPACK
218
219           If you're using VMStar:
220
221                VMStar xf Your-Module.tar
222
223           Or, if you're fond of VMS command syntax:
224
225                tar/extract/verbose Your_Module.tar
226
227           C. BUILD
228
229           Make sure you have MMS (from Digital) or the freeware MMK (
230           available from MadGoat at <http://www.madgoat.com> ).  Then type
231           this to create the DESCRIP.MMS for the module:
232
233               perl Makefile.PL
234
235           Now you're ready to build:
236
237               mms test
238
239           Substitute "mmk" for "mms" above if you're using MMK.
240
241           D. INSTALL
242
243           Type
244
245               mms install
246
247           Substitute "mmk" for "mms" above if you're using MMK.
248
249If you're on MVS,
250
251           Introduce the .tar.gz file into an HFS as binary; don't translate
252           from ASCII to EBCDIC.
253
254           A. DECOMPRESS
255
256           Decompress the file with "gzip -d yourmodule.tar.gz"
257
258           You can get gzip from
259           <http://www.s390.ibm.com/products/oe/bpxqp1.html>
260
261           B. UNPACK
262
263           Unpack the result with
264
265                pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
266
267           The BUILD and INSTALL steps are identical to those for Unix.  Some
268           modules generate Makefiles that work better with GNU make, which is
269           available from <http://www.mks.com/s390/gnu/>
270

PORTABILITY

272       Note that not all modules will work with on all platforms.  See
273       perlport for more information on portability issues.  Read the
274       documentation to see if the module will work on your system.  There are
275       basically three categories of modules that will not work "out of the
276       box" with all platforms (with some possibility of overlap):
277
278Those that should, but don't.  These need to be fixed; consider
279           contacting the author and possibly writing a patch.
280
281Those that need to be compiled, where the target platform doesn't
282           have compilers readily available.  (These modules contain .xs or .c
283           files, usually.)  You might be able to find existing binaries on
284           the CPAN or elsewhere, or you might want to try getting compilers
285           and building it yourself, and then release the binary for other
286           poor souls to use.
287
288Those that are targeted at a specific platform.  (Such as the
289           Win32:: modules.)  If the module is targeted specifically at a
290           platform other than yours, you're out of luck, most likely.
291
292       Check the CPAN Testers if a module should work with your platform but
293       it doesn't behave as you'd expect, or you aren't sure whether or not a
294       module will work under your platform.  If the module you want isn't
295       listed there, you can test it yourself and let CPAN Testers know, you
296       can join CPAN Testers, or you can request it be tested.
297
298           https://cpantesters.org/
299

HEY

301       If you have any suggested changes for this page, let me know.  Please
302       don't send me mail asking for help on how to install your modules.
303       There are too many modules, and too few Orwants, for me to be able to
304       answer or even acknowledge all your questions.  Contact the module
305       author instead, ask someone familiar with Perl on your operating
306       system, or if all else fails, file a ticket at <https://rt.cpan.org/>.
307

AUTHOR

309       Jon Orwant
310
311       orwant@medita.mit.edu
312
313       with invaluable help from Chris Nandor, and valuable help from Brandon
314       Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
315       Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
316       Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
317       Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
318
319       First version July 22, 1998; last revised November 21, 2001.
320
322       Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
323
324       This document may be distributed under the same terms as Perl itself.
325
326
327
328perl v5.34.0                      2021-10-18                 PERLMODINSTALL(1)
Impressum