local-lib5/man/man3/ExtUtils::Install.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ExtUtils::Install 3"
 132 .TH ExtUtils::Install 3 "2009-07-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::Install \- install files from here to there
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use ExtUtils::Install;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&  install({ 'blib/lib' => 'some/install/dir' } );
 143 .Ve
 144 .PP
 145 .Vb 1
 146 \&  uninstall($packlist);
 147 .Ve
 148 .PP
 149 .Vb 1
 150 \&  pm_to_blib({ 'lib/Foo/Bar.pm' => 'blib/lib/Foo/Bar.pm' });
 151 .Ve
 152 .SH "VERSION"
 153 .IX Header "VERSION"
 154 1.54
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 Handles the installing and uninstalling of perl modules, scripts, man
 158 pages, etc...
 159 .PP
 160 Both \fIinstall()\fR and \fIuninstall()\fR are specific to the way
 161 ExtUtils::MakeMaker handles the installation and deinstallation of
 162 perl modules. They are not designed as general purpose tools.
 163 .PP
 164 On some operating systems such as Win32 installation may not be possible
 165 until after a reboot has occured. This can have varying consequences:
 166 removing an old \s-1DLL\s0 does not impact programs using the new one, but if
 167 a new \s-1DLL\s0 cannot be installed properly until reboot then anything
 168 depending on it must wait. The package variable
 169 .PP
 170 .Vb 1
 171 \&  $ExtUtils::Install::MUST_REBOOT
 172 .Ve
 173 .PP
 174 is used to store this status.
 175 .PP
 176 If this variable is true then such an operation has occured and
 177 anything depending on this module cannot proceed until a reboot
 178 has occured.
 179 .PP
 180 If this value is defined but false then such an operation has
 181 ocurred, but should not impact later operations.
 182 .Sh "Functions"
 183 .IX Subsection "Functions"
 184 .IP "\fBinstall\fR" 4
 185 .IX Item "install"
 186 .Vb 4
 187 \&    # deprecated forms
 188 \&    install(\e%from_to);
 189 \&    install(\e%from_to, $verbose, $dry_run, $uninstall_shadows,
 190 \&                $skip, $always_copy, \e%result);
 191 .Ve
 192 .Sp
 193 .Vb 10
 194 \&    # recommended form as of 1.47
 195 \&    install([
 196 \&        from_to => \e%from_to,
 197 \&        verbose => 1,
 198 \&        dry_run => 0,
 199 \&        uninstall_shadows => 1,
 200 \&        skip => undef,
 201 \&        always_copy => 1,
 202 \&        result => \e%install_results,
 203 \&    ]);
 204 .Ve
 205 .Sp
 206 Copies each directory tree of \f(CW%from_to\fR to its corresponding value
 207 preserving timestamps and permissions.
 208 .Sp
 209 There are two keys with a special meaning in the hash: \*(L"read\*(R" and
 210 \&\*(L"write\*(R".  These contain packlist files.  After the copying is done,
 211 \&\fIinstall()\fR will write the list of target files to \f(CW$from_to\fR{write}. If
 212 \&\f(CW$from_to\fR{read} is given the contents of this file will be merged into
 213 the written file. The read and the written file may be identical, but
 214 on \s-1AFS\s0 it is quite likely that people are installing to a different
 215 directory than the one where the files later appear.
 216 .Sp
 217 If \f(CW$verbose\fR is true, will print out each file removed.  Default is
 218 false.  This is \*(L"make install VERBINST=1\*(R". \f(CW$verbose\fR values going
 219 up to 5 show increasingly more diagnostics output.
 220 .Sp
 221 If \f(CW$dry_run\fR is true it will only print what it was going to do
 222 without actually doing it.  Default is false.
 223 .Sp
 224 If \f(CW$uninstall_shadows\fR is true any differing versions throughout \f(CW@INC\fR
 225 will be uninstalled.  This is \*(L"make install UNINST=1\*(R"
 226 .Sp
 227 As of 1.37_02 \fIinstall()\fR supports the use of a list of patterns to filter out
 228 files that shouldn't be installed. If \f(CW$skip\fR is omitted or undefined then
 229 install will try to read the list from \s-1INSTALL\s0.SKIP in the \s-1CWD\s0. This file is
 230 a list of regular expressions and is just like the \s-1MANIFEST\s0.SKIP file used
 231 by ExtUtils::Manifest.
 232 .Sp
 233 A default site \s-1INSTALL\s0.SKIP may be provided by setting then environment
 234 variable \s-1EU_INSTALL_SITE_SKIPFILE\s0, this will only be used when there isn't a
 235 distribution specific \s-1INSTALL\s0.SKIP. If the environment variable
 236 \&\s-1EU_INSTALL_IGNORE_SKIP\s0 is true then no install file filtering will be
 237 performed.
 238 .Sp
 239 If \f(CW$skip\fR is undefined then the skip file will be autodetected and used if it
 240 is found. If \f(CW$skip\fR is a reference to an array then it is assumed the array
 241 contains the list of patterns, if \f(CW$skip\fR is a true non reference it is
 242 assumed to be the filename holding the list of patterns, any other value of
 243 \&\f(CW$skip\fR is taken to mean that no install filtering should occur.
 244 .Sp
 245 \&\fBChanges As of Version 1.47\fR
 246 .Sp
 247 As of version 1.47 the following additions were made to the install interface.
 248 Note that the new argument style and use of the \f(CW%result\fR hash is recommended.
 249 .Sp
 250 The \f(CW$always_copy\fR parameter which when true causes files to be updated
 251 regardles as to whether they have changed, if it is defined but false then
 252 copies are made only if the files have changed, if it is undefined then the
 253 value of the environment variable \s-1EU_INSTALL_ALWAYS_COPY\s0 is used as default.
 254 .Sp
 255 The \f(CW%result\fR hash will be populated with the various keys/subhashes reflecting
 256 the install. Currently these keys and their structure are:
 257 .Sp
 258 .Vb 3
 259 \&    install             => { $target    => $source },
 260 \&    install_fail        => { $target    => $source },
 261 \&    install_unchanged   => { $target    => $source },
 262 .Ve
 263 .Sp
 264 .Vb 1
 265 \&    install_filtered    => { $source    => $pattern },
 266 .Ve
 267 .Sp
 268 .Vb 2
 269 \&    uninstall           => { $uninstalled => $source },
 270 \&    uninstall_fail      => { $uninstalled => $source },
 271 .Ve
 272 .Sp
 273 where \f(CW$source\fR is the filespec of the file being installed. \f(CW$target\fR is where
 274 it is being installed to, and \f(CW$uninstalled\fR is any shadow file that is in \f(CW@INC\fR
 275 or \f(CW$ENV{PERL5LIB}\fR or other standard locations, and \f(CW$pattern\fR is the pattern that
 276 caused a source file to be skipped. In future more keys will be added, such as to
 277 show created directories, however this requires changes in other modules and must
 278 therefore wait.
 279 .Sp
 280 These keys will be populated before any exceptions are thrown should there be an
 281 error.
 282 .Sp
 283 Note that all updates of the \f(CW%result\fR are additive, the hash will not be
 284 cleared before use, thus allowing status results of many installs to be easily
 285 aggregated.
 286 .Sp
 287 \&\fB\s-1NEW\s0 \s-1ARGUMENT\s0 \s-1STYLE\s0\fR
 288 .Sp
 289 If there is only one argument and it is a reference to an array then
 290 the array is assumed to contain a list of key-value pairs specifying
 291 the options. In this case the option \*(L"from_to\*(R" is mandatory. This style
 292 means that you dont have to supply a cryptic list of arguments and can
 293 use a self documenting argument list that is easier to understand.
 294 .Sp
 295 This is now the recommended interface to \fIinstall()\fR.
 296 .Sp
 297 \&\fB\s-1RETURN\s0\fR
 298 .Sp
 299 If all actions were successful install will return a hashref of the results
 300 as described above for the \f(CW$result\fR parameter. If any action is a failure
 301 then install will die, therefore it is recommended to pass in the \f(CW$result\fR
 302 parameter instead of using the return value. If the result parameter is
 303 provided then the returned hashref will be the passed in hashref.
 304 .IP "\fBinstall_default\fR \fI\s-1DISCOURAGED\s0\fR" 4
 305 .IX Item "install_default DISCOURAGED"
 306 .Vb 2
 307 \&    install_default();
 308 \&    install_default($fullext);
 309 .Ve
 310 .Sp
 311 Calls \fIinstall()\fR with arguments to copy a module from blib/ to the
 312 default site installation location.
 313 .Sp
 314 $fullext is the name of the module converted to a directory
 315 (ie. Foo::Bar would be Foo/Bar).  If \f(CW$fullext\fR is not specified, it
 316 will attempt to read it from \f(CW@ARGV\fR.
 317 .Sp
 318 This is primarily useful for install scripts.
 319 .Sp
 320 \&\fB\s-1NOTE\s0\fR This function is not really useful because of the hard-coded
 321 install location with no way to control site vs core vs vendor
 322 directories and the strange way in which the module name is given.
 323 Consider its use discouraged.
 324 .IP "\fBuninstall\fR" 4
 325 .IX Item "uninstall"
 326 .Vb 2
 327 \&    uninstall($packlist_file);
 328 \&    uninstall($packlist_file, $verbose, $dont_execute);
 329 .Ve
 330 .Sp
 331 Removes the files listed in a \f(CW$packlist_file\fR.
 332 .Sp
 333 If \f(CW$verbose\fR is true, will print out each file removed.  Default is
 334 false.
 335 .Sp
 336 If \f(CW$dont_execute\fR is true it will only print what it was going to do
 337 without actually doing it.  Default is false.
 338 .IP "\fBpm_to_blib\fR" 4
 339 .IX Item "pm_to_blib"
 340 .Vb 2
 341 \&    pm_to_blib(\e%from_to, $autosplit_dir);
 342 \&    pm_to_blib(\e%from_to, $autosplit_dir, $filter_cmd);
 343 .Ve
 344 .Sp
 345 Copies each key of \f(CW%from_to\fR to its corresponding value efficiently.
 346 Filenames with the extension .pm are autosplit into the \f(CW$autosplit_dir\fR.
 347 Any destination directories are created.
 348 .Sp
 349 $filter_cmd is an optional shell command to run each .pm file through
 350 prior to splitting and copying.  Input is the contents of the module,
 351 output the new module contents.
 352 .Sp
 353 You can have an environment variable \s-1PERL_INSTALL_ROOT\s0 set which will
 354 be prepended as a directory to each installed file (and directory).
 355 .SH "ENVIRONMENT"
 356 .IX Header "ENVIRONMENT"
 357 .IP "\fB\s-1PERL_INSTALL_ROOT\s0\fR" 4
 358 .IX Item "PERL_INSTALL_ROOT"
 359 Will be prepended to each install path.
 360 .IP "\fB\s-1EU_INSTALL_IGNORE_SKIP\s0\fR" 4
 361 .IX Item "EU_INSTALL_IGNORE_SKIP"
 362 Will prevent the automatic use of \s-1INSTALL\s0.SKIP as the install skip file.
 363 .IP "\fB\s-1EU_INSTALL_SITE_SKIPFILE\s0\fR" 4
 364 .IX Item "EU_INSTALL_SITE_SKIPFILE"
 365 If there is no \s-1INSTALL\s0.SKIP file in the make directory then this value
 366 can be used to provide a default.
 367 .IP "\fB\s-1EU_INSTALL_ALWAYS_COPY\s0\fR" 4
 368 .IX Item "EU_INSTALL_ALWAYS_COPY"
 369 If this environment variable is true then normal install processes will
 370 always overwrite older identical files during the install process.
 371 .Sp
 372 Note that the alias \s-1EU_ALWAYS_COPY\s0 will be supported if \s-1EU_INSTALL_ALWAYS_COPY\s0
 373 is not defined until at least the 1.50 release. Please ensure you use the
 374 correct \s-1EU_INSTALL_ALWAYS_COPY\s0.
 375 .SH "AUTHOR"
 376 .IX Header "AUTHOR"
 377 Original author lost in the mists of time.  Probably the same as Makemaker.
 378 .PP
 379 Production release currently maintained by demerphq \f(CW\*(C`yves at cpan.org\*(C'\fR,
 380 extensive changes by Michael G. Schwern.
 381 .PP
 382 Send bug reports via http://rt.cpan.org/.  Please send your
 383 generated Makefile along with your report.
 384 .SH "LICENSE"
 385 .IX Header "LICENSE"
 386 This program is free software; you can redistribute it and/or
 387 modify it under the same terms as Perl itself.
 388 .PP
 389 See <http://www.perl.com/perl/misc/Artistic.html>