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 <http://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       <http://www.cpan.org/> , and searched at <http://search.cpan.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
58       ·   If you're on a Unix or Unix-like system,
59
60           You can use Andreas Koenig's CPAN module (
61           <http://www.cpan.org/modules/by-module/CPAN> ) to automate the
62           following 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
109       ·   If 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 shareware Winzip ( <http://www.winzip.com> ) to
121           decompress and unpack modules.
122
123              B. UNPACK
124
125           If you used WinZip, this was already done for you.
126
127              C. BUILD
128
129           You'll need the "nmake" utility, available at
130           <http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe>
131           or dmake, available on CPAN.  <http://search.cpan.org/dist/dmake/>
132
133           Does the module require compilation (i.e. does it have files that
134           end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, life is now
135           officially tough for you, because you have to compile the module
136           yourself (no easy feat on Windows).  You'll need a compiler such as
137           Visual C++.  Alternatively, you can download a pre-built PPM
138           package from ActiveState.
139           <http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
140
141           Go into the newly-created directory and type:
142
143                 perl Makefile.PL
144                 nmake test
145
146
147              D. INSTALL
148
149           While still in that directory, type:
150
151                 nmake install
152
153       ·   If you're on the DJGPP port of DOS,
154
155              A. DECOMPRESS
156
157           djtarx ( <ftp://ftp.delorie.com/pub/djgpp/current/v2/> ) will both
158           uncompress and unpack.
159
160              B. UNPACK
161
162           See above.
163
164              C. BUILD
165
166           Go into the newly-created directory and type:
167
168                 perl Makefile.PL
169                 make test
170
171           You will need the packages mentioned in README.dos in the Perl
172           distribution.
173
174              D. INSTALL
175
176           While still in that directory, type:
177
178                make install
179
180           You will need the packages mentioned in README.dos in the Perl
181           distribution.
182
183       ·   If you're on OS/2,
184
185           Get the EMX development suite and gzip/tar, from either Hobbes (
186           <http://hobbes.nmsu.edu> ) or Leo ( <http://www.leo.org> ), and
187           then follow the instructions for Unix.
188
189       ·   If you're on VMS,
190
191           When downloading from CPAN, save your file with a ".tgz" extension
192           instead of ".tar.gz".  All other periods in the filename should be
193           replaced with underscores.  For example, "Your-Module-1.33.tar.gz"
194           should be downloaded as "Your-Module-1_33.tgz".
195
196           A. DECOMPRESS
197
198           Type
199
200               gzip -d Your-Module.tgz
201
202           or, for zipped modules, type
203
204               unzip Your-Module.zip
205
206           Executables for gzip, zip, and VMStar:
207
208               http://www.hp.com/go/openvms/freeware/
209
210           and their source code:
211
212               http://www.fsf.org/order/ftp.html
213
214           Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
215           package.  The former is a simple compression tool; the latter
216           permits creation of multi-file archives.
217
218           B. UNPACK
219
220           If you're using VMStar:
221
222                VMStar xf Your-Module.tar
223
224           Or, if you're fond of VMS command syntax:
225
226                tar/extract/verbose Your_Module.tar
227
228           C. BUILD
229
230           Make sure you have MMS (from Digital) or the freeware MMK (
231           available from MadGoat at <http://www.madgoat.com> ).  Then type
232           this to create the DESCRIP.MMS for the module:
233
234               perl Makefile.PL
235
236           Now you're ready to build:
237
238               mms test
239
240           Substitute "mmk" for "mms" above if you're using MMK.
241
242           D. INSTALL
243
244           Type
245
246               mms install
247
248           Substitute "mmk" for "mms" above if you're using MMK.
249
250       ·   If you're on MVS,
251
252           Introduce the .tar.gz file into an HFS as binary; don't translate
253           from ASCII to EBCDIC.
254
255           A. DECOMPRESS
256
257           Decompress the file with "gzip -d yourmodule.tar.gz"
258
259           You can get gzip from
260           <http://www.s390.ibm.com/products/oe/bpxqp1.html>
261
262           B. UNPACK
263
264           Unpack the result with
265
266                pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
267
268           The BUILD and INSTALL steps are identical to those for Unix.  Some
269           modules generate Makefiles that work better with GNU make, which is
270           available from <http://www.mks.com/s390/gnu/>
271

PORTABILITY

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

HEY

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

AUTHOR

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