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 <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 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 <https://metacpan.org/release/CPAN> ) to automate the following
62 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 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 • 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 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 B. UNPACK
125 If you used WinZip, this was already done for you.
127 C. BUILD
129 You'll need the "nmake" utility, available at
131 <http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe>
132 or dmake, available on CPAN. <https://metacpan.org/release/dmake>
133 Does the module require compilation (i.e. does it have files that
135 end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
136 officially tough for you, because you have to compile the module
137 yourself (no easy feat on Windows). You'll need a compiler such as
138 Visual C++. Alternatively, you can download a pre-built PPM
139 package from ActiveState.
140 <http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
141 Go into the newly-created directory and type:
143 perl Makefile.PL
145 nmake test
146 D. INSTALL
149 While still in that directory, type:
151 nmake install
153 • If you're on the DJGPP port of DOS,
155 A. DECOMPRESS
157 djtarx ( <ftp://ftp.delorie.com/pub/djgpp/current/v2/> ) will both
159 uncompress and unpack.
160 B. UNPACK
162 See above.
164 C. BUILD
166 Go into the newly-created directory and type:
168 perl Makefile.PL
170 make test
171 You will need the packages mentioned in README.dos in the Perl
173 distribution.
174 D. INSTALL
176 While still in that directory, type:
178 make install
180 You will need the packages mentioned in README.dos in the Perl
182 distribution.
183 • If you're on OS/2,
185 Get the EMX development suite and gzip/tar from Hobbes (
187 <http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d> ),
188 and then follow the instructions for Unix.
189 • If you're on VMS,
191 When downloading from CPAN, save your file with a ".tgz" extension
193 instead of ".tar.gz". All other periods in the filename should be
194 replaced with underscores. For example, "Your-Module-1.33.tar.gz"
195 should be downloaded as "Your-Module-1_33.tgz".
196 A. DECOMPRESS
198 Type
200 gzip -d Your-Module.tgz
202 or, for zipped modules, type
204 unzip Your-Module.zip
206 Executables for gzip, zip, and VMStar:
208 http://www.hp.com/go/openvms/freeware/
210 and their source code:
212 http://www.fsf.org/order/ftp.html
214 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
216 package. The former is a simple compression tool; the latter
217 permits creation of multi-file archives.
218 B. UNPACK
220 If you're using VMStar:
222 VMStar xf Your-Module.tar
224 Or, if you're fond of VMS command syntax:
226 tar/extract/verbose Your_Module.tar
228 C. BUILD
230 Make sure you have MMS (from Digital) or the freeware MMK (
232 available from MadGoat at <http://www.madgoat.com> ). Then type
233 this to create the DESCRIP.MMS for the module:
234 perl Makefile.PL
236 Now you're ready to build:
238 mms test
240 Substitute "mmk" for "mms" above if you're using MMK.
242 D. INSTALL
244 Type
246 mms install
248 Substitute "mmk" for "mms" above if you're using MMK.
250 • If you're on MVS,
252 Introduce the .tar.gz file into an HFS as binary; don't translate
254 from ASCII to EBCDIC.
255 A. DECOMPRESS
257 Decompress the file with "gzip -d yourmodule.tar.gz"
259 You can get gzip from
261 <http://www.s390.ibm.com/products/oe/bpxqp1.html>
262 B. UNPACK
264 Unpack the result with
266 pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
268 The BUILD and INSTALL steps are identical to those for Unix. Some
270 modules generate Makefiles that work better with GNU make, which is
271 available from <http://www.mks.com/s390/gnu/>
272
274 Note that not all modules will work with on all platforms. See
275 perlport for more information on portability issues. Read the
276 documentation to see if the module will work on your system. There are
277 basically three categories of modules that will not work "out of the
278 box" with all platforms (with some possibility of overlap):
279 • Those that should, but don't. These need to be fixed; consider
281 contacting the author and possibly writing a patch.
282 • Those that need to be compiled, where the target platform doesn't
284 have compilers readily available. (These modules contain .xs or .c
285 files, usually.) You might be able to find existing binaries on
286 the CPAN or elsewhere, or you might want to try getting compilers
287 and building it yourself, and then release the binary for other
288 poor souls to use.
289 • Those that are targeted at a specific platform. (Such as the
291 Win32:: modules.) If the module is targeted specifically at a
292 platform other than yours, you're out of luck, most likely.
293 Check the CPAN Testers if a module should work with your platform but
295 it doesn't behave as you'd expect, or you aren't sure whether or not a
296 module will work under your platform. If the module you want isn't
297 listed there, you can test it yourself and let CPAN Testers know, you
298 can join CPAN Testers, or you can request it be tested.
299 https://cpantesters.org/
301
303 If you have any suggested changes for this page, let me know. Please
304 don't send me mail asking for help on how to install your modules.
305 There are too many modules, and too few Orwants, for me to be able to
306 answer or even acknowledge all your questions. Contact the module
307 author instead, ask someone familiar with Perl on your operating
308 system, or if all else fails, file a ticket at <https://rt.cpan.org/>.
309
311 Jon Orwant
312 orwant@medita.mit.edu
314 with invaluable help from Chris Nandor, and valuable help from Brandon
316 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
317 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
318 Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
319 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
320 First version July 22, 1998; last revised November 21, 2001.
322
324 Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
325 This document may be distributed under the same terms as Perl itself.
327perl v5.32.1 2021-05-31 PERLMODINSTALL(1)