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 they
13 can then upload their code to the CPAN. The CPAN is the Comprehensive
14 Perl Archive Network and can be accessed at http://www.cpan.org/ , and
15 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
22 First, are you sure that the module isn't already on your system? Try
23 "perl -MFoo -e 1". (Replace "Foo" with the name of the module; for
24 instance, "perl -MCGI::Carp -e 1".
25
26 If you don't see an error message, you have the module. (If you do see
27 an error message, it's still possible you have the module, but that
28 it's not in your path, which you can display with "perl -e "print
29 qq(@INC)"".) For the remainder of this document, we'll assume that you
30 really honestly truly lack an installed module, but have found it on
31 the CPAN.
32
33 So now you have a file ending in .tar.gz (or, less often, .zip). You
34 know there's a tasty module inside. There are four steps you must now
35 take:
36
37 DECOMPRESS the file
38 UNPACK the file into a directory
39 BUILD the module (sometimes unnecessary)
40 INSTALL the module.
41
42 Here's how to perform each step for each operating system. This is
43 <not> a substitute for reading the README and INSTALL files that might
44 have come with your module!
45
46 Also note that these instructions are tailored for installing the mod‐
47 ule into your system's repository of Perl modules -- but you can
48 install modules into any directory you wish. For instance, where I say
49 "perl Makefile.PL", you can substitute "perl Makefile.PL PRE‐
50 FIX=/my/perl_directory" to install the modules into "/my/perl_direc‐
51 tory". Then you can use the modules from your Perl programs with "use
52 lib "/my/perl_directory/lib/site_perl";" or sometimes just "use
53 "/my/perl_directory";". If you're on a system that requires supe‐
54 ruser/root access to install modules into the directories you see when
55 you type "perl -e "print qq(@INC)"", you'll want to install them into a
56 local directory (such as your home directory) and 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 ( http://www.cpan.org/mod‐
61 ules/by-module/CPAN ) to automate the following steps, from DECOM‐
62 PRESS 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 mod‐
100 ule 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
105 for another reason you have a statically-linked perl, and the mod‐
106 ule requires compilation, you'll need to build a new Perl binary
107 that 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 http://download.mi‐
130 crosoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe or
131 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
137 as Visual C++. Alternatively, you can download a pre-built PPM
138 package from ActiveState. http://aspn.activestate.com/ASPN/Down‐
139 loads/ActivePerl/PPM/
140
141 Go into the newly-created directory and type:
142
143 perl Makefile.PL
144 nmake test
145
146 D. INSTALL
147
148 While still in that directory, type:
149
150 nmake install
151
152 · If you're using a Macintosh with "Classic" MacOS and MacPerl,
153
154 A. DECOMPRESS
155
156 First, make sure you have the latest cpan-mac distribution (
157 http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
158 doing all of the steps. Read the cpan-mac directions carefully and
159 install it. If you choose not to use cpan-mac for some reason,
160 there are alternatives listed here.
161
162 After installing cpan-mac, drop the module archive on the
163 untarzipme droplet, which will decompress and unpack for you.
164
165 Or, you can either use the shareware StuffIt Expander program (
166 http://www.aladdinsys.com/expander/ ) in combination with DropStuff
167 with Expander Enhancer ( http://www.aladdinsys.com/dropstuff/ ) or
168 the freeware MacGzip program ( http://persephone.cps.unizar.es/gen‐
169 eral/gente/spd/gzip/gzip.html ).
170
171 B. UNPACK
172
173 If you're using untarzipme or StuffIt, the archive should be
174 extracted now. Or, you can use the freeware suntar or Tar (
175 http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
176
177 C. BUILD
178
179 Check the contents of the distribution. Read the module's documen‐
180 tation, looking for reasons why you might have trouble using it
181 with MacPerl. Look for .xs and .c files, which normally denote
182 that the distribution must be compiled, and you cannot install it
183 "out of the box." (See "PORTABILITY".)
184
185 If a module does not work on MacPerl but should, or needs to be
186 compiled, see if the module exists already as a port on the MacPerl
187 Module Porters site ( http://pudge.net/mmp/ ). For more informa‐
188 tion on doing XS with MacPerl yourself, see Arved Sandstrom's XS
189 tutorial ( http://macperl.com/depts/Tutorials/ ), and then consider
190 uploading your binary to the CPAN and registering it on the MMP
191 site.
192
193 D. INSTALL
194
195 If you are using cpan-mac, just drop the folder on the installme
196 droplet, and use the module.
197
198 Or, if you aren't using cpan-mac, do some manual labor.
199
200 Make sure the newlines for the modules are in Mac format, not Unix
201 format. If they are not then you might have decompressed them
202 incorrectly. Check your decompression and unpacking utilities set‐
203 tings to make sure they are translating text files properly.
204
205 As a last resort, you can use the perl one-liner:
206
207 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
208
209 on the source files.
210
211 Then move the files (probably just the .pm files, though there may
212 be some additional ones, too; check the module documentation) to
213 their final destination: This will most likely be in
214 "$ENV{MACPERL}site_lib:" (i.e., "HD:MacPerl folder:site_lib:").
215 You can add new paths to the default @INC in the Preferences menu
216 item in the MacPerl application ("$ENV{MACPERL}site_lib:" is added
217 automagically). Create whatever directory structures are required
218 (i.e., for "Some::Module", create "$ENV{MACPERL}site_lib:Some:" and
219 put "Module.pm" in that directory).
220
221 Then run the following script (or something like it):
222
223 #!perl -w
224 use AutoSplit;
225 my $dir = "${MACPERL}site_perl";
226 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
227
228 · If you're on the DJGPP port of DOS,
229
230 A. DECOMPRESS
231
232 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) will
233 both uncompress and unpack.
234
235 B. UNPACK
236
237 See above.
238
239 C. BUILD
240
241 Go into the newly-created directory and type:
242
243 perl Makefile.PL
244 make test
245
246 You will need the packages mentioned in README.dos in the Perl dis‐
247 tribution.
248
249 D. INSTALL
250
251 While still in that directory, type:
252
253 make install
254
255 You will need the packages mentioned in README.dos in the Perl dis‐
256 tribution.
257
258 · If you're on OS/2,
259
260 Get the EMX development suite and gzip/tar, from either Hobbes (
261 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then
262 follow the instructions for Unix.
263
264 · If you're on VMS,
265
266 When downloading from CPAN, save your file with a ".tgz" extension
267 instead of ".tar.gz". All other periods in the filename should be
268 replaced with underscores. For example, "Your-Module-1.33.tar.gz"
269 should be downloaded as "Your-Module-1_33.tgz".
270
271 A. DECOMPRESS
272
273 Type
274
275 gzip -d Your-Module.tgz
276
277 or, for zipped modules, type
278
279 unzip Your-Module.zip
280
281 Executables for gzip, zip, and VMStar:
282
283 http://www.openvms.digital.com/freeware/
284 http://www.crinoid.com/utils/
285
286 and their source code:
287
288 http://www.fsf.org/order/ftp.html
289
290 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
291 package. The former is a simple compression tool; the latter per‐
292 mits creation of multi-file archives.
293
294 B. UNPACK
295
296 If you're using VMStar:
297
298 VMStar xf Your-Module.tar
299
300 Or, if you're fond of VMS command syntax:
301
302 tar/extract/verbose Your_Module.tar
303
304 C. BUILD
305
306 Make sure you have MMS (from Digital) or the freeware MMK ( avail‐
307 able from MadGoat at http://www.madgoat.com ). Then type this to
308 create the DESCRIP.MMS for the module:
309
310 perl Makefile.PL
311
312 Now you're ready to build:
313
314 mms test
315
316 Substitute "mmk" for "mms" above if you're using MMK.
317
318 D. INSTALL
319
320 Type
321
322 mms install
323
324 Substitute "mmk" for "mms" above if you're using MMK.
325
326 · If you're on MVS,
327
328 Introduce the .tar.gz file into an HFS as binary; don't translate
329 from ASCII to EBCDIC.
330
331 A. DECOMPRESS
332
333 Decompress the file with "gzip -d yourmodule.tar.gz"
334
335 You can get gzip from http://www.s390.ibm.com/prod‐
336 ucts/oe/bpxqp1.html
337
338 B. UNPACK
339
340 Unpack the result with
341
342 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
343
344 The BUILD and INSTALL steps are identical to those for Unix. Some
345 modules generate Makefiles that work better with GNU make, which is
346 available from http://www.mks.com/s390/gnu/
347
349 Note that not all modules will work with on all platforms. See perl‐
350 port for more information on portability issues. Read the documenta‐
351 tion to see if the module will work on your system. There are basi‐
352 cally three categories of modules that will not work "out of the box"
353 with all platforms (with some possibility of overlap):
354
355 · Those that should, but don't. These need to be fixed; consider
356 contacting the author and possibly writing a patch.
357
358 · Those that need to be compiled, where the target platform doesn't
359 have compilers readily available. (These modules contain .xs or .c
360 files, usually.) You might be able to find existing binaries on
361 the CPAN or elsewhere, or you might want to try getting compilers
362 and building it yourself, and then release the binary for other
363 poor souls to use.
364
365 · Those that are targeted at a specific platform. (Such as the
366 Win32:: modules.) If the module is targeted specifically at a
367 platform other than yours, you're out of luck, most likely.
368
369 Check the CPAN Testers if a module should work with your platform but
370 it doesn't behave as you'd expect, or you aren't sure whether or not a
371 module will work under your platform. If the module you want isn't
372 listed there, you can test it yourself and let CPAN Testers know, you
373 can join CPAN Testers, or you can request it be tested.
374
375 http://testers.cpan.org/
376
378 If you have any suggested changes for this page, let me know. Please
379 don't send me mail asking for help on how to install your modules.
380 There are too many modules, and too few Orwants, for me to be able to
381 answer or even acknowledge all your questions. Contact the module
382 author instead, or post to comp.lang.perl.modules, or ask someone
383 familiar with Perl on your operating system.
384
386 Jon Orwant
387
388 orwant@medita.mit.edu
389
390 with invaluable help from Chris Nandor, and valuable help from Brandon
391 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
392 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
393 Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
394 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
395
396 First version July 22, 1998; last revised November 21, 2001.
397
399 Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
400
401 Permission is granted to make and distribute verbatim copies of this
402 documentation provided the copyright notice and this permission notice
403 are preserved on all copies.
404
405 Permission is granted to copy and distribute modified versions of this
406 documentation under the conditions for verbatim copying, provided also
407 that they are marked clearly as modified versions, that the authors'
408 names and title are unchanged (though subtitles and additional authors'
409 names may be added), and that the entire resulting derived work is dis‐
410 tributed under the terms of a permission notice identical to this one.
411
412 Permission is granted to copy and distribute translations of this docu‐
413 mentation into another language, under the above conditions for modi‐
414 fied versions.
415
416
417
418perl v5.8.8 2006-01-07 PERLMODINSTALL(1)