1PERLMODINSTALL(1) Perl Programmers Reference Guide PERLMODINSTALL(1)
2
3
4
6 perlmodinstall - Installing CPAN Modules
7
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 using a Macintosh with "Classic" MacOS and MacPerl,
154
155 A. DECOMPRESS
156
157 First, make sure you have the latest cpan-mac distribution (
158 <http://www.cpan.org/authors/id/CNANDOR/> ), which has utilities
159 for doing all of the steps. Read the cpan-mac directions carefully
160 and install it. If you choose not to use cpan-mac for some reason,
161 there are alternatives listed here.
162
163 After installing cpan-mac, drop the module archive on the
164 untarzipme droplet, which will decompress and unpack for you.
165
166 Or, you can either use the shareware StuffIt Expander program (
167 <http://my.smithmicro.com/mac/stuffit/> ) or the freeware MacGzip
168 program (
169 <http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html>
170 ).
171
172 B. UNPACK
173
174 If you're using untarzipme or StuffIt, the archive should be
175 extracted now. Or, you can use the freeware suntar or Tar (
176 <http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/> ).
177
178 C. BUILD
179
180 Check the contents of the distribution. Read the module's
181 documentation, looking for reasons why you might have trouble using
182 it with MacPerl. Look for .xs and .c files, which normally denote
183 that the distribution must be compiled, and you cannot install it
184 "out of the box." (See "PORTABILITY".)
185
186 D. INSTALL
187
188 If you are using cpan-mac, just drop the folder on the installme
189 droplet, and use the module.
190
191 Or, if you aren't using cpan-mac, do some manual labor.
192
193 Make sure the newlines for the modules are in Mac format, not Unix
194 format. If they are not then you might have decompressed them
195 incorrectly. Check your decompression and unpacking utilities
196 settings to make sure they are translating text files properly.
197
198 As a last resort, you can use the perl one-liner:
199
200 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
201
202 on the source files.
203
204 Then move the files (probably just the .pm files, though there may
205 be some additional ones, too; check the module documentation) to
206 their final destination: This will most likely be in
207 "$ENV{MACPERL}site_lib:" (i.e., "HD:MacPerl folder:site_lib:").
208 You can add new paths to the default @INC in the Preferences menu
209 item in the MacPerl application ("$ENV{MACPERL}site_lib:" is added
210 automagically). Create whatever directory structures are required
211 (i.e., for "Some::Module", create "$ENV{MACPERL}site_lib:Some:" and
212 put "Module.pm" in that directory).
213
214 Then run the following script (or something like it):
215
216 #!perl -w
217 use AutoSplit;
218 my $dir = "${MACPERL}site_perl";
219 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
220
221 · If you're on the DJGPP port of DOS,
222
223 A. DECOMPRESS
224
225 djtarx ( <ftp://ftp.delorie.com/pub/djgpp/current/v2/> ) will both
226 uncompress and unpack.
227
228 B. UNPACK
229
230 See above.
231
232 C. BUILD
233
234 Go into the newly-created directory and type:
235
236 perl Makefile.PL
237 make test
238
239 You will need the packages mentioned in README.dos in the Perl
240 distribution.
241
242 D. INSTALL
243
244 While still in that directory, type:
245
246 make install
247
248 You will need the packages mentioned in README.dos in the Perl
249 distribution.
250
251 · If you're on OS/2,
252
253 Get the EMX development suite and gzip/tar, from either Hobbes (
254 <http://hobbes.nmsu.edu> ) or Leo ( <http://www.leo.org> ), and
255 then follow the instructions for Unix.
256
257 · If you're on VMS,
258
259 When downloading from CPAN, save your file with a ".tgz" extension
260 instead of ".tar.gz". All other periods in the filename should be
261 replaced with underscores. For example, "Your-Module-1.33.tar.gz"
262 should be downloaded as "Your-Module-1_33.tgz".
263
264 A. DECOMPRESS
265
266 Type
267
268 gzip -d Your-Module.tgz
269
270 or, for zipped modules, type
271
272 unzip Your-Module.zip
273
274 Executables for gzip, zip, and VMStar:
275
276 http://www.hp.com/go/openvms/freeware/
277
278 and their source code:
279
280 http://www.fsf.org/order/ftp.html
281
282 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
283 package. The former is a simple compression tool; the latter
284 permits creation of multi-file archives.
285
286 B. UNPACK
287
288 If you're using VMStar:
289
290 VMStar xf Your-Module.tar
291
292 Or, if you're fond of VMS command syntax:
293
294 tar/extract/verbose Your_Module.tar
295
296 C. BUILD
297
298 Make sure you have MMS (from Digital) or the freeware MMK (
299 available from MadGoat at <http://www.madgoat.com> ). Then type
300 this to create the DESCRIP.MMS for the module:
301
302 perl Makefile.PL
303
304 Now you're ready to build:
305
306 mms test
307
308 Substitute "mmk" for "mms" above if you're using MMK.
309
310 D. INSTALL
311
312 Type
313
314 mms install
315
316 Substitute "mmk" for "mms" above if you're using MMK.
317
318 · If you're on MVS,
319
320 Introduce the .tar.gz file into an HFS as binary; don't translate
321 from ASCII to EBCDIC.
322
323 A. DECOMPRESS
324
325 Decompress the file with "gzip -d yourmodule.tar.gz"
326
327 You can get gzip from
328 <http://www.s390.ibm.com/products/oe/bpxqp1.html>
329
330 B. UNPACK
331
332 Unpack the result with
333
334 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
335
336 The BUILD and INSTALL steps are identical to those for Unix. Some
337 modules generate Makefiles that work better with GNU make, which is
338 available from <http://www.mks.com/s390/gnu/>
339
341 Note that not all modules will work with on all platforms. See
342 perlport for more information on portability issues. Read the
343 documentation to see if the module will work on your system. There are
344 basically three categories of modules that will not work "out of the
345 box" with all platforms (with some possibility of overlap):
346
347 · Those that should, but don't. These need to be fixed; consider
348 contacting the author and possibly writing a patch.
349
350 · Those that need to be compiled, where the target platform doesn't
351 have compilers readily available. (These modules contain .xs or .c
352 files, usually.) You might be able to find existing binaries on
353 the CPAN or elsewhere, or you might want to try getting compilers
354 and building it yourself, and then release the binary for other
355 poor souls to use.
356
357 · Those that are targeted at a specific platform. (Such as the
358 Win32:: modules.) If the module is targeted specifically at a
359 platform other than yours, you're out of luck, most likely.
360
361 Check the CPAN Testers if a module should work with your platform but
362 it doesn't behave as you'd expect, or you aren't sure whether or not a
363 module will work under your platform. If the module you want isn't
364 listed there, you can test it yourself and let CPAN Testers know, you
365 can join CPAN Testers, or you can request it be tested.
366
367 http://testers.cpan.org/
368
370 If you have any suggested changes for this page, let me know. Please
371 don't send me mail asking for help on how to install your modules.
372 There are too many modules, and too few Orwants, for me to be able to
373 answer or even acknowledge all your questions. Contact the module
374 author instead, ask someone familiar with Perl on your operating
375 system, or if all else fails, file a ticket at http://rt.cpan.org/.
376
378 Jon Orwant
379
380 orwant@medita.mit.edu
381
382 with invaluable help from Chris Nandor, and valuable help from Brandon
383 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
384 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
385 Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
386 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
387
388 First version July 22, 1998; last revised November 21, 2001.
389
391 Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
392
393 This document may be distributed under the same terms as Perl itself.
394
395
396
397perl v5.26.3 2018-03-23 PERLMODINSTALL(1)