Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Install.3perl

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