Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perlmodinstall.1

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