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

PORTABILITY

242       Note that not all modules will work with on all platforms.  See
243       perlport for more information on portability issues.  Read the
244       documentation to see if the module will work on your system.  There are
245       basically three categories of modules that will not work "out of the
246       box" with all platforms (with some possibility of overlap):
247
248Those that should, but don't.  These need to be fixed; consider
249           contacting the author and possibly writing a patch.
250
251Those that need to be compiled, where the target platform doesn't
252           have compilers readily available.  (These modules contain .xs or .c
253           files, usually.)  You might be able to find existing binaries on
254           the CPAN or elsewhere, or you might want to try getting compilers
255           and building it yourself, and then release the binary for other
256           poor souls to use.
257
258Those that are targeted at a specific platform.  (Such as the
259           Win32:: modules.)  If the module is targeted specifically at a
260           platform other than yours, you're out of luck, most likely.
261
262       Check the CPAN Testers if a module should work with your platform but
263       it doesn't behave as you'd expect, or you aren't sure whether or not a
264       module will work under your platform.  If the module you want isn't
265       listed there, you can test it yourself and let CPAN Testers know, you
266       can join CPAN Testers, or you can request it be tested.
267
268           https://cpantesters.org/
269

HEY

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

AUTHOR

279       Jon Orwant
280
281       orwant@medita.mit.edu
282
283       with invaluable help from Chris Nandor, and valuable help from Brandon
284       Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
285       Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J.
286       Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
287       Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
288
289       First version July 22, 1998; last revised November 21, 2001.
290
292       Copyright (C) 1998, 2002, 2003 Jon Orwant.  All Rights Reserved.
293
294       This document may be distributed under the same terms as Perl itself.
295
296
297
298perl v5.38.2                      2023-11-30                 PERLMODINSTALL(1)
Impressum