Debian Codegraph @

upstream/opensuse-tumbleweed/man3/ExtUtils::Install.3pm

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 "ExtUtils::Install 3pm"
61 .TH ExtUtils::Install 3pm 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 ExtUtils::Install \- install files from here to there
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use ExtUtils::Install;
72 \&
73 \& install({ \*(Aqblib/lib\*(Aq => \*(Aqsome/install/dir\*(Aq } );
74 \&
75 \& uninstall($packlist);
76 \&
77 \& pm_to_blib({ \*(Aqlib/Foo/Bar.pm\*(Aq => \*(Aqblib/lib/Foo/Bar.pm\*(Aq });
78 .Ve
79 .SH VERSION
80 .IX Header "VERSION"
81 2.22
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 Handles the installing and uninstalling of perl modules, scripts, man
85 pages, etc...
86 .PP
87 Both \fBinstall()\fR and \fBuninstall()\fR are specific to the way
88 ExtUtils::MakeMaker handles the installation and deinstallation of
89 perl modules. They are not designed as general purpose tools.
90 .PP
91 On some operating systems such as Win32 installation may not be possible
92 until after a reboot has occurred. This can have varying consequences:
93 removing an old DLL does not impact programs using the new one, but if
94 a new DLL cannot be installed properly until reboot then anything
95 depending on it must wait. The package variable
96 .PP
97 .Vb 1
98 \& $ExtUtils::Install::MUST_REBOOT
99 .Ve
100 .PP
101 is used to store this status.
102 .PP
103 If this variable is true then such an operation has occurred and
104 anything depending on this module cannot proceed until a reboot
105 has occurred.
106 .PP
107 If this value is defined but false then such an operation has
108 occurred, but should not impact later operations.
109 .SH Functions
110 .IX Header "Functions"
111 .SS install
112 .IX Subsection "install"
113 .Vb 4
114 \& # deprecated forms
115 \& install(\e%from_to);
116 \& install(\e%from_to, $verbose, $dry_run, $uninstall_shadows,
117 \& $skip, $always_copy, \e%result);
118 \&
119 \& # recommended form as of 1.47
120 \& install([
121 \& from_to => \e%from_to,
122 \& verbose => 1,
123 \& dry_run => 0,
124 \& uninstall_shadows => 1,
125 \& skip => undef,
126 \& always_copy => 1,
127 \& result => \e%install_results,
128 \& ]);
129 .Ve
130 .PP
131 Copies each directory tree of \f(CW%from_to\fR to its corresponding value
132 preserving timestamps and permissions.
133 .PP
134 There are two keys with a special meaning in the hash: "read" and
135 "write". These contain packlist files. After the copying is done,
136 \&\fBinstall()\fR will write the list of target files to \f(CW$from_to\fR{write}. If
137 \&\f(CW$from_to\fR{read} is given the contents of this file will be merged into
138 the written file. The read and the written file may be identical, but
139 on AFS it is quite likely that people are installing to a different
140 directory than the one where the files later appear.
141 .PP
142 If \f(CW$verbose\fR is true, will print out each file removed. Default is
143 false. This is "make install VERBINST=1". \f(CW$verbose\fR values going
144 up to 5 show increasingly more diagnostics output.
145 .PP
146 If \f(CW$dry_run\fR is true it will only print what it was going to do
147 without actually doing it. Default is false.
148 .PP
149 If \f(CW$uninstall_shadows\fR is true any differing versions throughout \f(CW@INC\fR
150 will be uninstalled. This is "make install UNINST=1"
151 .PP
152 As of 1.37_02 \fBinstall()\fR supports the use of a list of patterns to filter out
153 files that shouldn\*(Aqt be installed. If \f(CW$skip\fR is omitted or undefined then
154 install will try to read the list from INSTALL.SKIP in the CWD. This file is
155 a list of regular expressions and is just like the MANIFEST.SKIP file used
156 by ExtUtils::Manifest.
157 .PP
158 A default site INSTALL.SKIP may be provided by setting then environment
159 variable EU_INSTALL_SITE_SKIPFILE, this will only be used when there isn\*(Aqt a
160 distribution specific INSTALL.SKIP. If the environment variable
161 EU_INSTALL_IGNORE_SKIP is true then no install file filtering will be
162 performed.
163 .PP
164 If \f(CW$skip\fR is undefined then the skip file will be autodetected and used if it
165 is found. If \f(CW$skip\fR is a reference to an array then it is assumed the array
166 contains the list of patterns, if \f(CW$skip\fR is a true non reference it is
167 assumed to be the filename holding the list of patterns, any other value of
168 \&\f(CW$skip\fR is taken to mean that no install filtering should occur.
169 .PP
170 \&\fBChanges As of Version 1.47\fR
171 .PP
172 As of version 1.47 the following additions were made to the install interface.
173 Note that the new argument style and use of the \f(CW%result\fR hash is recommended.
174 .PP
175 The \f(CW$always_copy\fR parameter which when true causes files to be updated
176 regardless as to whether they have changed, if it is defined but false then
177 copies are made only if the files have changed, if it is undefined then the
178 value of the environment variable EU_INSTALL_ALWAYS_COPY is used as default.
179 .PP
180 The \f(CW%result\fR hash will be populated with the various keys/subhashes reflecting
181 the install. Currently these keys and their structure are:
182 .PP
183 .Vb 3
184 \& install => { $target => $source },
185 \& install_fail => { $target => $source },
186 \& install_unchanged => { $target => $source },
187 \&
188 \& install_filtered => { $source => $pattern },
189 \&
190 \& uninstall => { $uninstalled => $source },
191 \& uninstall_fail => { $uninstalled => $source },
192 .Ve
193 .PP
194 where \f(CW$source\fR is the filespec of the file being installed. \f(CW$target\fR is where
195 it is being installed to, and \f(CW$uninstalled\fR is any shadow file that is in \f(CW@INC\fR
196 or \f(CW$ENV{PERL5LIB}\fR or other standard locations, and \f(CW$pattern\fR is the pattern that
197 caused a source file to be skipped. In future more keys will be added, such as to
198 show created directories, however this requires changes in other modules and must
199 therefore wait.
200 .PP
201 These keys will be populated before any exceptions are thrown should there be an
202 error.
203 .PP
204 Note that all updates of the \f(CW%result\fR are additive, the hash will not be
205 cleared before use, thus allowing status results of many installs to be easily
206 aggregated.
207 .PP
208 \&\fBNEW ARGUMENT STYLE\fR
209 .PP
210 If there is only one argument and it is a reference to an array then
211 the array is assumed to contain a list of key\-value pairs specifying
212 the options. In this case the option "from_to" is mandatory. This style
213 means that you do not have to supply a cryptic list of arguments and can
214 use a self documenting argument list that is easier to understand.
215 .PP
216 This is now the recommended interface to \fBinstall()\fR.
217 .PP
218 \&\fBRETURN\fR
219 .PP
220 If all actions were successful install will return a hashref of the results
221 as described above for the \f(CW$result\fR parameter. If any action is a failure
222 then install will die, therefore it is recommended to pass in the \f(CW$result\fR
223 parameter instead of using the return value. If the result parameter is
224 provided then the returned hashref will be the passed in hashref.
225 .SS install_default
226 .IX Subsection "install_default"
227 \&\fIDISCOURAGED\fR
228 .PP
229 .Vb 2
230 \& install_default();
231 \& install_default($fullext);
232 .Ve
233 .PP
234 Calls \fBinstall()\fR with arguments to copy a module from blib/ to the
235 default site installation location.
236 .PP
237 \&\f(CW$fullext\fR is the name of the module converted to a directory
238 (ie. Foo::Bar would be Foo/Bar). If \f(CW$fullext\fR is not specified, it
239 will attempt to read it from \f(CW@ARGV\fR.
240 .PP
241 This is primarily useful for install scripts.
242 .PP
243 \&\fBNOTE\fR This function is not really useful because of the hard\-coded
244 install location with no way to control site vs core vs vendor
245 directories and the strange way in which the module name is given.
246 Consider its use discouraged.
247 .SS uninstall
248 .IX Subsection "uninstall"
249 .Vb 2
250 \& uninstall($packlist_file);
251 \& uninstall($packlist_file, $verbose, $dont_execute);
252 .Ve
253 .PP
254 Removes the files listed in a \f(CW$packlist_file\fR.
255 .PP
256 If \f(CW$verbose\fR is true, will print out each file removed. Default is
257 false.
258 .PP
259 If \f(CW$dont_execute\fR is true it will only print what it was going to do
260 without actually doing it. Default is false.
261 .SS pm_to_blib
262 .IX Subsection "pm_to_blib"
263 .Vb 3
264 \& pm_to_blib(\e%from_to);
265 \& pm_to_blib(\e%from_to, $autosplit_dir);
266 \& pm_to_blib(\e%from_to, $autosplit_dir, $filter_cmd);
267 .Ve
268 .PP
269 Copies each key of \f(CW%from_to\fR to its corresponding value efficiently.
270 If an \f(CW$autosplit_dir\fR is provided, all .pm files will be autosplit into it.
271 Any destination directories are created.
272 .PP
273 \&\f(CW$filter_cmd\fR is an optional shell command to run each .pm file through
274 prior to splitting and copying. Input is the contents of the module,
275 output the new module contents.
276 .PP
277 You can have an environment variable PERL_INSTALL_ROOT set which will
278 be prepended as a directory to each installed file (and directory).
279 .PP
280 By default verbose output is generated, setting the PERL_INSTALL_QUIET
281 environment variable will silence this output.
282 .SH ENVIRONMENT
283 .IX Header "ENVIRONMENT"
284 .IP \fBPERL_INSTALL_ROOT\fR 4
285 .IX Item "PERL_INSTALL_ROOT"
286 Will be prepended to each install path.
287 .IP \fBEU_INSTALL_IGNORE_SKIP\fR 4
288 .IX Item "EU_INSTALL_IGNORE_SKIP"
289 Will prevent the automatic use of INSTALL.SKIP as the install skip file.
290 .IP \fBEU_INSTALL_SITE_SKIPFILE\fR 4
291 .IX Item "EU_INSTALL_SITE_SKIPFILE"
292 If there is no INSTALL.SKIP file in the make directory then this value
293 can be used to provide a default.
294 .IP \fBEU_INSTALL_ALWAYS_COPY\fR 4
295 .IX Item "EU_INSTALL_ALWAYS_COPY"
296 If this environment variable is true then normal install processes will
297 always overwrite older identical files during the install process.
298 .Sp
299 Note that the alias EU_ALWAYS_COPY will be supported if EU_INSTALL_ALWAYS_COPY
300 is not defined until at least the 1.50 release. Please ensure you use the
301 correct EU_INSTALL_ALWAYS_COPY.
302 .SH AUTHOR
303 .IX Header "AUTHOR"
304 Original author lost in the mists of time. Probably the same as Makemaker.
305 .PP
306 Production release currently maintained by demerphq \f(CW\*(C`yves at cpan.org\*(C'\fR,
307 extensive changes by Michael G. Schwern.
308 .PP
309 Send bug reports via http://rt.cpan.org/. Please send your
310 generated Makefile along with your report.
311 .SH LICENSE
312 .IX Header "LICENSE"
313 This program is free software; you can redistribute it and/or
314 modify it under the same terms as Perl itself.
315 .PP
316 See <http://www.perl.com/perl/misc/Artistic.html>