1ExtUtils::Install(3)  User Contributed Perl Documentation ExtUtils::Install(3)
2
3
4

NAME

6       ExtUtils::Install - install files from here to there
7

SYNOPSIS

9         use ExtUtils::Install;
10
11         install({ 'blib/lib' => 'some/install/dir' } );
12
13         uninstall($packlist);
14
15         pm_to_blib({ 'lib/Foo/Bar.pm' => 'blib/lib/Foo/Bar.pm' });
16

VERSION

18       2.22
19

DESCRIPTION

21       Handles the installing and uninstalling of perl modules, scripts, man
22       pages, etc...
23
24       Both install() and uninstall() are specific to the way
25       ExtUtils::MakeMaker handles the installation and deinstallation of perl
26       modules. They are not designed as general purpose tools.
27
28       On some operating systems such as Win32 installation may not be
29       possible until after a reboot has occurred. This can have varying
30       consequences: removing an old DLL does not impact programs using the
31       new one, but if a new DLL cannot be installed properly until reboot
32       then anything depending on it must wait. The package variable
33
34         $ExtUtils::Install::MUST_REBOOT
35
36       is used to store this status.
37
38       If this variable is true then such an operation has occurred and
39       anything depending on this module cannot proceed until a reboot has
40       occurred.
41
42       If this value is defined but false then such an operation has occurred,
43       but should not impact later operations.
44

Functions

46   install
47           # deprecated forms
48           install(\%from_to);
49           install(\%from_to, $verbose, $dry_run, $uninstall_shadows,
50                       $skip, $always_copy, \%result);
51
52           # recommended form as of 1.47
53           install([
54               from_to => \%from_to,
55               verbose => 1,
56               dry_run => 0,
57               uninstall_shadows => 1,
58               skip => undef,
59               always_copy => 1,
60               result => \%install_results,
61           ]);
62
63       Copies each directory tree of %from_to to its corresponding value
64       preserving timestamps and permissions.
65
66       There are two keys with a special meaning in the hash: "read" and
67       "write".  These contain packlist files.  After the copying is done,
68       install() will write the list of target files to $from_to{write}. If
69       $from_to{read} is given the contents of this file will be merged into
70       the written file. The read and the written file may be identical, but
71       on AFS it is quite likely that people are installing to a different
72       directory than the one where the files later appear.
73
74       If $verbose is true, will print out each file removed.  Default is
75       false.  This is "make install VERBINST=1". $verbose values going up to
76       5 show increasingly more diagnostics output.
77
78       If $dry_run is true it will only print what it was going to do without
79       actually doing it.  Default is false.
80
81       If $uninstall_shadows is true any differing versions throughout @INC
82       will be uninstalled.  This is "make install UNINST=1"
83
84       As of 1.37_02 install() supports the use of a list of patterns to
85       filter out files that shouldn't be installed. If $skip is omitted or
86       undefined then install will try to read the list from INSTALL.SKIP in
87       the CWD. This file is a list of regular expressions and is just like
88       the MANIFEST.SKIP file used by ExtUtils::Manifest.
89
90       A default site INSTALL.SKIP may be provided by setting then environment
91       variable EU_INSTALL_SITE_SKIPFILE, this will only be used when there
92       isn't a distribution specific INSTALL.SKIP. If the environment variable
93       EU_INSTALL_IGNORE_SKIP is true then no install file filtering will be
94       performed.
95
96       If $skip is undefined then the skip file will be autodetected and used
97       if it is found. If $skip is a reference to an array then it is assumed
98       the array contains the list of patterns, if $skip is a true non
99       reference it is assumed to be the filename holding the list of
100       patterns, any other value of $skip is taken to mean that no install
101       filtering should occur.
102
103       Changes As of Version 1.47
104
105       As of version 1.47 the following additions were made to the install
106       interface.  Note that the new argument style and use of the %result
107       hash is recommended.
108
109       The $always_copy parameter which when true causes files to be updated
110       regardless as to whether they have changed, if it is defined but false
111       then copies are made only if the files have changed, if it is undefined
112       then the value of the environment variable EU_INSTALL_ALWAYS_COPY is
113       used as default.
114
115       The %result hash will be populated with the various keys/subhashes
116       reflecting the install. Currently these keys and their structure are:
117
118           install             => { $target    => $source },
119           install_fail        => { $target    => $source },
120           install_unchanged   => { $target    => $source },
121
122           install_filtered    => { $source    => $pattern },
123
124           uninstall           => { $uninstalled => $source },
125           uninstall_fail      => { $uninstalled => $source },
126
127       where $source is the filespec of the file being installed. $target is
128       where it is being installed to, and $uninstalled is any shadow file
129       that is in @INC or $ENV{PERL5LIB} or other standard locations, and
130       $pattern is the pattern that caused a source file to be skipped. In
131       future more keys will be added, such as to show created directories,
132       however this requires changes in other modules and must therefore wait.
133
134       These keys will be populated before any exceptions are thrown should
135       there be an error.
136
137       Note that all updates of the %result are additive, the hash will not be
138       cleared before use, thus allowing status results of many installs to be
139       easily aggregated.
140
141       NEW ARGUMENT STYLE
142
143       If there is only one argument and it is a reference to an array then
144       the array is assumed to contain a list of key-value pairs specifying
145       the options. In this case the option "from_to" is mandatory. This style
146       means that you do not have to supply a cryptic list of arguments and
147       can use a self documenting argument list that is easier to understand.
148
149       This is now the recommended interface to install().
150
151       RETURN
152
153       If all actions were successful install will return a hashref of the
154       results as described above for the $result parameter. If any action is
155       a failure then install will die, therefore it is recommended to pass in
156       the $result parameter instead of using the return value. If the result
157       parameter is provided then the returned hashref will be the passed in
158       hashref.
159
160   install_default
161       DISCOURAGED
162
163           install_default();
164           install_default($fullext);
165
166       Calls install() with arguments to copy a module from blib/ to the
167       default site installation location.
168
169       $fullext is the name of the module converted to a directory (ie.
170       Foo::Bar would be Foo/Bar).  If $fullext is not specified, it will
171       attempt to read it from @ARGV.
172
173       This is primarily useful for install scripts.
174
175       NOTE This function is not really useful because of the hard-coded
176       install location with no way to control site vs core vs vendor
177       directories and the strange way in which the module name is given.
178       Consider its use discouraged.
179
180   uninstall
181           uninstall($packlist_file);
182           uninstall($packlist_file, $verbose, $dont_execute);
183
184       Removes the files listed in a $packlist_file.
185
186       If $verbose is true, will print out each file removed.  Default is
187       false.
188
189       If $dont_execute is true it will only print what it was going to do
190       without actually doing it.  Default is false.
191
192   pm_to_blib
193           pm_to_blib(\%from_to);
194           pm_to_blib(\%from_to, $autosplit_dir);
195           pm_to_blib(\%from_to, $autosplit_dir, $filter_cmd);
196
197       Copies each key of %from_to to its corresponding value efficiently.  If
198       an $autosplit_dir is provided, all .pm files will be autosplit into it.
199       Any destination directories are created.
200
201       $filter_cmd is an optional shell command to run each .pm file through
202       prior to splitting and copying.  Input is the contents of the module,
203       output the new module contents.
204
205       You can have an environment variable PERL_INSTALL_ROOT set which will
206       be prepended as a directory to each installed file (and directory).
207
208       By default verbose output is generated, setting the PERL_INSTALL_QUIET
209       environment variable will silence this output.
210

ENVIRONMENT

212       PERL_INSTALL_ROOT
213           Will be prepended to each install path.
214
215       EU_INSTALL_IGNORE_SKIP
216           Will prevent the automatic use of INSTALL.SKIP as the install skip
217           file.
218
219       EU_INSTALL_SITE_SKIPFILE
220           If there is no INSTALL.SKIP file in the make directory then this
221           value can be used to provide a default.
222
223       EU_INSTALL_ALWAYS_COPY
224           If this environment variable is true then normal install processes
225           will always overwrite older identical files during the install
226           process.
227
228           Note that the alias EU_ALWAYS_COPY will be supported if
229           EU_INSTALL_ALWAYS_COPY is not defined until at least the 1.50
230           release. Please ensure you use the correct EU_INSTALL_ALWAYS_COPY.
231

AUTHOR

233       Original author lost in the mists of time.  Probably the same as
234       Makemaker.
235
236       Production release currently maintained by demerphq "yves at cpan.org",
237       extensive changes by Michael G. Schwern.
238
239       Send bug reports via http://rt.cpan.org/.  Please send your generated
240       Makefile along with your report.
241

LICENSE

243       This program is free software; you can redistribute it and/or modify it
244       under the same terms as Perl itself.
245
246       See <http://www.perl.com/perl/misc/Artistic.html>
247
248
249
250perl v5.36.0                      2023-01-20              ExtUtils::Install(3)
Impressum