1PERLMODINSTALL(1) Perl Programmers Reference Guide PERLMODINSTALL(1)
2
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 This documentation is for people who want to download CPAN modules and
18 install them on their own computer.
19 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 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 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 DECOMPRESS the file
37 UNPACK the file into a directory
38 BUILD the module (sometimes unnecessary)
39 INSTALL the module.
40 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 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 · If you're on a Unix or Unix-like system,
59 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 A. DECOMPRESS
65 Decompress the file with "gzip -d yourmodule.tar.gz"
67 You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
69 Or, you can combine this step with the next to save disk space:
71 gzip -dc yourmodule.tar.gz | tar -xof -
73 B. UNPACK
75 Unpack the result with "tar -xof yourmodule.tar"
77 C. BUILD
79 Go into the newly-created directory and type:
81 perl Makefile.PL
83 make test
84 or
86 perl Makefile.PL PREFIX=/my/perl_directory
88 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 D. INSTALL
94 While still in that directory, type:
96 make install
98 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 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
106 module 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 · If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)
110 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 A. DECOMPRESS
119 You can use the shareware Winzip ( http://www.winzip.com ) to
121 decompress and unpack modules.
122 B. UNPACK
124 If you used WinZip, this was already done for you.
126 C. BUILD
128 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 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.
139 http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
140 Go into the newly-created directory and type:
142 perl Makefile.PL
144 nmake test
145 D. INSTALL
148 While still in that directory, type:
150 nmake install
152 · If you're using a Macintosh with "Classic" MacOS and MacPerl,
154 A. DECOMPRESS
156 First, make sure you have the latest cpan-mac distribution (
158 http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
159 doing all of the steps. Read the cpan-mac directions carefully and
160 install it. If you choose not to use cpan-mac for some reason,
161 there are alternatives listed here.
162 After installing cpan-mac, drop the module archive on the
164 untarzipme droplet, which will decompress and unpack for you.
165 Or, you can either use the shareware StuffIt Expander program (
167 http://www.aladdinsys.com/expander/ ) in combination with DropStuff
168 with Expander Enhancer ( http://www.aladdinsys.com/dropstuff/ ) or
169 the freeware MacGzip program (
170 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
171 B. UNPACK
173 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 C. BUILD
179 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 If a module does not work on MacPerl but should, or needs to be
187 compiled, see if the module exists already as a port on the MacPerl
188 Module Porters site ( http://pudge.net/mmp/ ). For more
189 information on doing XS with MacPerl yourself, see Arved
190 Sandstrom's XS tutorial ( http://macperl.com/depts/Tutorials/ ),
191 and then consider uploading your binary to the CPAN and registering
192 it on the MMP site.
193 D. INSTALL
195 If you are using cpan-mac, just drop the folder on the installme
197 droplet, and use the module.
198 Or, if you aren't using cpan-mac, do some manual labor.
200 Make sure the newlines for the modules are in Mac format, not Unix
202 format. If they are not then you might have decompressed them
203 incorrectly. Check your decompression and unpacking utilities
204 settings to make sure they are translating text files properly.
205 As a last resort, you can use the perl one-liner:
207 perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>
209 on the source files.
211 Then move the files (probably just the .pm files, though there may
213 be some additional ones, too; check the module documentation) to
214 their final destination: This will most likely be in
215 "$ENV{MACPERL}site_lib:" (i.e., "HD:MacPerl folder:site_lib:").
216 You can add new paths to the default @INC in the Preferences menu
217 item in the MacPerl application ("$ENV{MACPERL}site_lib:" is added
218 automagically). Create whatever directory structures are required
219 (i.e., for "Some::Module", create "$ENV{MACPERL}site_lib:Some:" and
220 put "Module.pm" in that directory).
221 Then run the following script (or something like it):
223 #!perl -w
225 use AutoSplit;
226 my $dir = "${MACPERL}site_perl";
227 autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
228 · If you're on the DJGPP port of DOS,
230 A. DECOMPRESS
232 djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) will
234 both uncompress and unpack.
235 B. UNPACK
237 See above.
239 C. BUILD
241 Go into the newly-created directory and type:
243 perl Makefile.PL
245 make test
246 You will need the packages mentioned in README.dos in the Perl
248 distribution.
249 D. INSTALL
251 While still in that directory, type:
253 make install
255 You will need the packages mentioned in README.dos in the Perl
257 distribution.
258 · If you're on OS/2,
260 Get the EMX development suite and gzip/tar, from either Hobbes (
262 http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then
263 follow the instructions for Unix.
264 · If you're on VMS,
266 When downloading from CPAN, save your file with a ".tgz" extension
268 instead of ".tar.gz". All other periods in the filename should be
269 replaced with underscores. For example, "Your-Module-1.33.tar.gz"
270 should be downloaded as "Your-Module-1_33.tgz".
271 A. DECOMPRESS
273 Type
275 gzip -d Your-Module.tgz
277 or, for zipped modules, type
279 unzip Your-Module.zip
281 Executables for gzip, zip, and VMStar:
283 http://www.openvms.digital.com/freeware/
285 http://www.crinoid.com/utils/
286 and their source code:
288 http://www.fsf.org/order/ftp.html
290 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
292 package. The former is a simple compression tool; the latter
293 permits creation of multi-file archives.
294 B. UNPACK
296 If you're using VMStar:
298 VMStar xf Your-Module.tar
300 Or, if you're fond of VMS command syntax:
302 tar/extract/verbose Your_Module.tar
304 C. BUILD
306 Make sure you have MMS (from Digital) or the freeware MMK (
308 available from MadGoat at http://www.madgoat.com ). Then type this
309 to create the DESCRIP.MMS for the module:
310 perl Makefile.PL
312 Now you're ready to build:
314 mms test
316 Substitute "mmk" for "mms" above if you're using MMK.
318 D. INSTALL
320 Type
322 mms install
324 Substitute "mmk" for "mms" above if you're using MMK.
326 · If you're on MVS,
328 Introduce the .tar.gz file into an HFS as binary; don't translate
330 from ASCII to EBCDIC.
331 A. DECOMPRESS
333 Decompress the file with "gzip -d yourmodule.tar.gz"
335 You can get gzip from
337 http://www.s390.ibm.com/products/oe/bpxqp1.html
338 B. UNPACK
340 Unpack the result with
342 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
344 The BUILD and INSTALL steps are identical to those for Unix. Some
346 modules generate Makefiles that work better with GNU make, which is
347 available from http://www.mks.com/s390/gnu/
348
350 Note that not all modules will work with on all platforms. See
351 perlport for more information on portability issues. Read the
352 documentation to see if the module will work on your system. There are
353 basically three categories of modules that will not work "out of the
354 box" with all platforms (with some possibility of overlap):
355 · Those that should, but don't. These need to be fixed; consider
357 contacting the author and possibly writing a patch.
358 · Those that need to be compiled, where the target platform doesn't
360 have compilers readily available. (These modules contain .xs or .c
361 files, usually.) You might be able to find existing binaries on
362 the CPAN or elsewhere, or you might want to try getting compilers
363 and building it yourself, and then release the binary for other
364 poor souls to use.
365 · Those that are targeted at a specific platform. (Such as the
367 Win32:: modules.) If the module is targeted specifically at a
368 platform other than yours, you're out of luck, most likely.
369 Check the CPAN Testers if a module should work with your platform but
371 it doesn't behave as you'd expect, or you aren't sure whether or not a
372 module will work under your platform. If the module you want isn't
373 listed there, you can test it yourself and let CPAN Testers know, you
374 can join CPAN Testers, or you can request it be tested.
375 http://testers.cpan.org/
377
379 If you have any suggested changes for this page, let me know. Please
380 don't send me mail asking for help on how to install your modules.
381 There are too many modules, and too few Orwants, for me to be able to
382 answer or even acknowledge all your questions. Contact the module
383 author instead, or post to comp.lang.perl.modules, or ask someone
384 familiar with Perl on your operating system.
385
387 Jon Orwant
388 orwant@medita.mit.edu
390 with invaluable help from Chris Nandor, and valuable help from Brandon
392 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
393 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
394 Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
395 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
396 First version July 22, 1998; last revised November 21, 2001.
398
400 Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
401 Permission is granted to make and distribute verbatim copies of this
403 documentation provided the copyright notice and this permission notice
404 are preserved on all copies.
405 Permission is granted to copy and distribute modified versions of this
407 documentation under the conditions for verbatim copying, provided also
408 that they are marked clearly as modified versions, that the authors'
409 names and title are unchanged (though subtitles and additional authors'
410 names may be added), and that the entire resulting derived work is
411 distributed under the terms of a permission notice identical to this
412 one.
413 Permission is granted to copy and distribute translations of this
415 documentation into another language, under the above conditions for
416 modified versions.
417perl v5.10.1 2009-02-12 PERLMODINSTALL(1)