Debian Codegraph @

upstream/debian-unstable/man1/perlmodinstall.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLMODINSTALL 1"
58 .TH PERLMODINSTALL 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlmodinstall \- Installing CPAN Modules
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 You can think of a module as the fundamental unit of reusable Perl
68 code; see perlmod for details. Whenever anyone creates a chunk of
69 Perl code that they think will be useful to the world, they register
70 as a Perl developer at <https://www.cpan.org/modules/04pause.html>
71 so that they can then upload their code to the CPAN. The CPAN is the
72 Comprehensive Perl Archive Network and can be accessed at
73 <https://www.cpan.org/> , and searched at <https://metacpan.org/> .
74 .PP
75 This documentation is for people who want to download CPAN modules
76 and install them on their own computer.
77 .SS PREAMBLE
78 .IX Subsection "PREAMBLE"
79 First, are you sure that the module isn't already on your system? Try
80 \&\f(CW\*(C`perl \-MFoo \-e 1\*(C'\fR. (Replace "Foo" with the name of the module; for
81 instance, \f(CW\*(C`perl \-MCGI::Carp \-e 1\*(C'\fR.)
82 .PP
83 If you don't see an error message, you have the module. (If you do
84 see an error message, it's still possible you have the module, but
85 that it's not in your path, which you can display with \f(CWperl \-e
86 "print qq(@INC)"\fR.) For the remainder of this document, we'll assume
87 that you really honestly truly lack an installed module, but have
88 found it on the CPAN.
89 .PP
90 So now you have a file ending in .tar.gz (or, less often, .zip). You
91 know there's a tasty module inside. There are four steps you must now
92 take:
93 .IP "\fBDECOMPRESS\fR the file" 5
94 .IX Item "DECOMPRESS the file"
95 .PD 0
96 .IP "\fBUNPACK\fR the file into a directory" 5
97 .IX Item "UNPACK the file into a directory"
98 .IP "\fBBUILD\fR the module (sometimes unnecessary)" 5
99 .IX Item "BUILD the module (sometimes unnecessary)"
100 .IP "\fBINSTALL\fR the module." 5
101 .IX Item "INSTALL the module."
102 .PD
103 .PP
104 Here's how to perform each step for each operating system. This is
105 <not> a substitute for reading the README and INSTALL files that
106 might have come with your module!
107 .PP
108 Also note that these instructions are tailored for installing the
109 module into your system's repository of Perl modules, but you can
110 install modules into any directory you wish. For instance, where I
111 say \f(CW\*(C`perl Makefile.PL\*(C'\fR, you can substitute \f(CW\*(C`perl Makefile.PL
112 PREFIX=/my/perl_directory\*(C'\fR to install the modules into
113 \&\fI/my/perl_directory\fR. Then you can use the modules from your Perl
114 programs with \f(CW\*(C`use lib "/my/perl_directory/lib/site_perl";\*(C'\fR or
115 sometimes just \f(CW\*(C`use "/my/perl_directory";\*(C'\fR. If you're on a system
116 that requires superuser/root access to install modules into the
117 directories you see when you type \f(CW\*(C`perl \-e "print qq(@INC)"\*(C'\fR, you'll
118 want to install them into a local directory (such as your home
119 directory) and use this approach.
120 .IP \(bu 4
121 \&\fBIf you're on a Unix or Unix-like system,\fR
122 .Sp
123 You can use Andreas Koenig's CPAN module
124 ( <https://metacpan.org/release/CPAN> )
125 to automate the following steps, from DECOMPRESS through INSTALL.
126 .Sp
127 A. DECOMPRESS
128 .Sp
129 Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR
130 .Sp
131 You can get gzip from <ftp://prep.ai.mit.edu/pub/gnu/>
132 .Sp
133 Or, you can combine this step with the next to save disk space:
134 .Sp
135 .Vb 1
136 \& gzip \-dc yourmodule.tar.gz | tar \-xof \-
137 .Ve
138 .Sp
139 B. UNPACK
140 .Sp
141 Unpack the result with \f(CW\*(C`tar \-xof yourmodule.tar\*(C'\fR
142 .Sp
143 C. BUILD
144 .Sp
145 Go into the newly-created directory and type:
146 .Sp
147 .Vb 2
148 \& perl Makefile.PL
149 \& make test
150 .Ve
151 .Sp
152 or
153 .Sp
154 .Vb 1
155 \& perl Makefile.PL PREFIX=/my/perl_directory
156 .Ve
157 .Sp
158 to install it locally. (Remember that if you do this, you'll have to
159 put \f(CW\*(C`use lib "/my/perl_directory";\*(C'\fR near the top of the program that
160 is to use this module.
161 .Sp
162 D. INSTALL
163 .Sp
164 While still in that directory, type:
165 .Sp
166 .Vb 1
167 \& make install
168 .Ve
169 .Sp
170 Make sure you have the appropriate permissions to install the module
171 in your Perl 5 library directory. Often, you'll need to be root.
172 .Sp
173 That's all you need to do on Unix systems with dynamic linking.
174 Most Unix systems have dynamic linking. If yours doesn't, or if for
175 another reason you have a statically-linked perl, \fBand\fR the
176 module requires compilation, you'll need to build a new Perl binary
177 that includes the module. Again, you'll probably need to be root.
178 .IP \(bu 4
179 \&\fBIf you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),\fR
180 .Sp
181 First, type \f(CW\*(C`ppm\*(C'\fR from a shell and see whether ActiveState's PPM
182 repository has your module. If so, you can install it with \f(CW\*(C`ppm\*(C'\fR and
183 you won't have to bother with any of the other steps here. You might
184 be able to use the CPAN instructions from the "Unix or Linux" section
185 above as well; give it a try. Otherwise, you'll have to follow the
186 steps below.
187 .Sp
188 .Vb 1
189 \& A. DECOMPRESS
190 .Ve
191 .Sp
192 You can use the
193 open source 7\-zip ( <https://www.7\-zip.org/> )
194 or the shareware Winzip ( <https://www.winzip.com> ) to
195 decompress and unpack modules.
196 .Sp
197 .Vb 1
198 \& B. UNPACK
199 .Ve
200 .Sp
201 If you used WinZip, this was already done for you.
202 .Sp
203 .Vb 1
204 \& C. BUILD
205 .Ve
206 .Sp
207 You'll need either \f(CW\*(C`nmake\*(C'\fR or \f(CW\*(C`gmake\*(C'\fR.
208 .Sp
209 Does the module require compilation (i.e. does it have files that end
210 in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
211 officially tough for you, because you have to compile the module
212 yourself (no easy feat on Windows). You'll need a compiler such as
213 Visual C++. Alternatively, you can download a pre-built PPM package
214 from ActiveState.
215 <http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/>
216 .Sp
217 Go into the newly-created directory and type:
218 .Sp
219 .Vb 2
220 \& perl Makefile.PL
221 \& nmake test
222 \&
223 \&
224 \& D. INSTALL
225 .Ve
226 .Sp
227 While still in that directory, type:
228 .Sp
229 .Vb 1
230 \& nmake install
231 .Ve
232 .IP \(bu 4
233 \&\fBIf you're on OS/2,\fR
234 .Sp
235 Get the EMX development suite and gzip/tar from Hobbes (
236 <http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2/dev/emx/v0.9d> ), and then follow
237 the instructions for Unix.
238 .IP \(bu 4
239 \&\fBIf you're on VMS,\fR
240 .Sp
241 When downloading from CPAN, save your file with a \f(CW\*(C`.tgz\*(C'\fR
242 extension instead of \f(CW\*(C`.tar.gz\*(C'\fR. All other periods in the
243 filename should be replaced with underscores. For example,
244 \&\f(CW\*(C`Your\-Module\-1.33.tar.gz\*(C'\fR should be downloaded as
245 \&\f(CW\*(C`Your\-Module\-1_33.tgz\*(C'\fR.
246 .Sp
247 A. DECOMPRESS
248 .Sp
249 Type
250 .Sp
251 .Vb 1
252 \& gzip \-d Your\-Module.tgz
253 .Ve
254 .Sp
255 or, for zipped modules, type
256 .Sp
257 .Vb 1
258 \& unzip Your\-Module.zip
259 .Ve
260 .Sp
261 Executables for gzip, zip, and VMStar:
262 .Sp
263 .Vb 1
264 \& http://www.hp.com/go/openvms/freeware/
265 .Ve
266 .Sp
267 and their source code:
268 .Sp
269 .Vb 1
270 \& http://www.fsf.org/order/ftp.html
271 .Ve
272 .Sp
273 Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
274 package. The former is a simple compression tool; the latter permits
275 creation of multi-file archives.
276 .Sp
277 B. UNPACK
278 .Sp
279 If you're using VMStar:
280 .Sp
281 .Vb 1
282 \& VMStar xf Your\-Module.tar
283 .Ve
284 .Sp
285 Or, if you're fond of VMS command syntax:
286 .Sp
287 .Vb 1
288 \& tar/extract/verbose Your_Module.tar
289 .Ve
290 .Sp
291 C. BUILD
292 .Sp
293 Make sure you have MMS (from Digital) or the freeware MMK ( available
294 from MadGoat at <http://www.madgoat.com> ). Then type this to create
295 the DESCRIP.MMS for the module:
296 .Sp
297 .Vb 1
298 \& perl Makefile.PL
299 .Ve
300 .Sp
301 Now you're ready to build:
302 .Sp
303 .Vb 1
304 \& mms test
305 .Ve
306 .Sp
307 Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK.
308 .Sp
309 D. INSTALL
310 .Sp
311 Type
312 .Sp
313 .Vb 1
314 \& mms install
315 .Ve
316 .Sp
317 Substitute \f(CW\*(C`mmk\*(C'\fR for \f(CW\*(C`mms\*(C'\fR above if you're using MMK.
318 .IP \(bu 4
319 \&\fBIf you're on MVS\fR,
320 .Sp
321 Introduce the \fI.tar.gz\fR file into an HFS as binary; don't translate from
322 ASCII to EBCDIC.
323 .Sp
324 A. DECOMPRESS
325 .Sp
326 Decompress the file with \f(CW\*(C`gzip \-d yourmodule.tar.gz\*(C'\fR
327 .Sp
328 You can get gzip from
329 <http://www.s390.ibm.com/products/oe/bpxqp1.html>
330 .Sp
331 B. UNPACK
332 .Sp
333 Unpack the result with
334 .Sp
335 .Vb 1
336 \& pax \-o to=IBM\-1047,from=ISO8859\-1 \-r < yourmodule.tar
337 .Ve
338 .Sp
339 The BUILD and INSTALL steps are identical to those for Unix. Some
340 modules generate Makefiles that work better with GNU make, which is
341 available from <http://www.mks.com/s390/gnu/>
342 .SH PORTABILITY
343 .IX Header "PORTABILITY"
344 Note that not all modules will work with on all platforms.
345 See perlport for more information on portability issues.
346 Read the documentation to see if the module will work on your
347 system. There are basically three categories
348 of modules that will not work "out of the box" with all
349 platforms (with some possibility of overlap):
350 .IP \(bu 4
351 \&\fBThose that should, but don't.\fR These need to be fixed; consider
352 contacting the author and possibly writing a patch.
353 .IP \(bu 4
354 \&\fBThose that need to be compiled, where the target platform
355 doesn't have compilers readily available.\fR (These modules contain
356 \&\fI.xs\fR or \fI.c\fR files, usually.) You might be able to find
357 existing binaries on the CPAN or elsewhere, or you might
358 want to try getting compilers and building it yourself, and then
359 release the binary for other poor souls to use.
360 .IP \(bu 4
361 \&\fBThose that are targeted at a specific platform.\fR
362 (Such as the Win32:: modules.) If the module is targeted
363 specifically at a platform other than yours, you're out
364 of luck, most likely.
365 .PP
366 Check the CPAN Testers if a module should work with your platform
367 but it doesn't behave as you'd expect, or you aren't sure whether or
368 not a module will work under your platform. If the module you want
369 isn't listed there, you can test it yourself and let CPAN Testers know,
370 you can join CPAN Testers, or you can request it be tested.
371 .PP
372 .Vb 1
373 \& https://cpantesters.org/
374 .Ve
375 .SH HEY
376 .IX Header "HEY"
377 If you have any suggested changes for this page, let me know. Please
378 don't send me mail asking for help on how to install your modules.
379 There are too many modules, and too few Orwants, for me to be able to
380 answer or even acknowledge all your questions. Contact the module
381 author instead, ask someone familiar with Perl on your operating
382 system, or if all else fails, file a ticket at <https://rt.cpan.org/>.
383 .SH AUTHOR
384 .IX Header "AUTHOR"
385 Jon Orwant
386 .PP
387 [email protected]
388 .PP
389 with invaluable help from Chris Nandor, and valuable help from Brandon
390 Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
391 Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
392 J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
393 Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
394 .PP
395 First version July 22, 1998; last revised November 21, 2001.
396 .SH COPYRIGHT
397 .IX Header "COPYRIGHT"
398 Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
399 .PP
400 This document may be distributed under the same terms as Perl itself.