local-lib5/man/man3/ExtUtils::Installed.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::Installed 3"
 132 .TH ExtUtils::Installed 3 "2009-07-19" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::Installed \- Inventory management of installed modules
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 9
 138 \&   use ExtUtils::Installed;
 139 \&   my ($inst) = ExtUtils::Installed\->new();
 140 \&   my (@modules) = $inst\->modules();
 141 \&   my (@missing) = $inst\->validate("DBI");
 142 \&   my $all_files = $inst\->files("DBI");
 143 \&   my $files_below_usr_local = $inst\->files("DBI", "all", "/usr/local");
 144 \&   my $all_dirs = $inst\->directories("DBI");
 145 \&   my $dirs_below_usr_local = $inst\->directory_tree("DBI", "prog");
 146 \&   my $packlist = $inst\->packlist("DBI");
 147 .Ve
 148 .SH "DESCRIPTION"
 149 .IX Header "DESCRIPTION"
 150 ExtUtils::Installed  provides a standard way to find out what core and module
 151 files have been installed.  It uses the information stored in .packlist files
 152 created during installation to provide this information.  In addition it
 153 provides facilities to classify the installed files and to extract directory
 154 information from the .packlist files.
 155 .SH "USAGE"
 156 .IX Header "USAGE"
 157 The \fInew()\fR function searches for all the installed .packlists on the system, and
 158 stores their contents. The .packlists can be queried with the functions
 159 described below. Where it searches by default is determined by the settings found
 160 in \f(CW%Config::Config\fR, and what the value is of the \s-1PERL5LIB\s0 environment variable.
 161 .SH "METHODS"
 162 .IX Header "METHODS"
 163 Unless specified otherwise all method can be called as class methods, or as object
 164 methods. If called as class methods then the \*(L"default\*(R" object will be used, and if
 165 necessary created using the current processes \f(CW%Config\fR and \f(CW@INC\fR.  See the
 166 \&'default' option to \fInew()\fR for details.
 167 .IP "\fInew()\fR" 4
 168 .IX Item "new()"
 169 This takes optional named parameters. Without parameters, this
 170 searches for all the installed .packlists on the system using
 171 information from \f(CW%Config::Config\fR and the default module search
 172 paths \f(CW@INC\fR. The packlists are read using the
 173 ExtUtils::Packlist module.
 174 .Sp
 175 If the named parameter \f(CW\*(C`config_override\*(C'\fR is specified,
 176 it should be a reference to a hash which contains all information
 177 usually found in \f(CW%Config::Config\fR. For example, you can obtain
 178 the configuration information for a separate perl installation and
 179 pass that in.
 180 .Sp
 181 .Vb 2
 182 \&    my $yoda_cfg  = get_fake_config('yoda');
 183 \&    my $yoda_inst = ExtUtils::Installed\->new(config_override=>$yoda_cfg);
 184 .Ve
 185 .Sp
 186 Similarly, the parameter \f(CW\*(C`inc_override\*(C'\fR may be a reference to an
 187 array which is used in place of the default module search paths
 188 from \f(CW@INC\fR.
 189 .Sp
 190 .Vb 3
 191 \&    use Config;
 192 \&    my @dirs = split(/\eQ$Config{path_sep}\eE/, $ENV{PERL5LIB});
 193 \&    my $p5libs = ExtUtils::Installed\->new(inc_override=>\e@dirs);
 194 .Ve
 195 .Sp
 196 \&\fBNote\fR: You probably do not want to use these options alone, almost always
 197 you will want to set both together.
 198 .Sp
 199 The parameter c<extra_libs> can be used to specify \fBadditional\fR paths to
 200 search for installed modules. For instance
 201 .Sp
 202 .Vb 1
 203 \&    my $installed = ExtUtils::Installed\->new(extra_libs=>["/my/lib/path"]);
 204 .Ve
 205 .Sp
 206 This should only be necessary if \f(CW\*(C`/my/lib/path\*(C'\fR is not in \s-1PERL5LIB\s0.
 207 .Sp
 208 Finally there is the 'default', and the related 'default_get' and 'default_set'
 209 options. These options control the \*(L"default\*(R" object which is provided by the
 210 class interface to the methods. Setting \f(CW\*(C`default_get\*(C'\fR to true tells the constructor
 211 to return the default object if it is defined. Setting \f(CW\*(C`default_set\*(C'\fR to true tells
 212 the constructor to make the default object the constructed object. Setting the
 213 \&\f(CW\*(C`default\*(C'\fR option is like setting both to true. This is used primarily internally
 214 and probably isn't interesting to any real user.
 215 .IP "\fImodules()\fR" 4
 216 .IX Item "modules()"
 217 This returns a list of the names of all the installed modules.  The perl 'core'
 218 is given the special name 'Perl'.
 219 .IP "\fIfiles()\fR" 4
 220 .IX Item "files()"
 221 This takes one mandatory parameter, the name of a module.  It returns a list of
 222 all the filenames from the package.  To obtain a list of core perl files, use
 223 the module name 'Perl'.  Additional parameters are allowed.  The first is one
 224 of the strings \*(L"prog\*(R", \*(L"doc\*(R" or \*(L"all\*(R", to select either just program files,
 225 just manual files or all files.  The remaining parameters are a list of
 226 directories. The filenames returned will be restricted to those under the
 227 specified directories.
 228 .IP "\fIdirectories()\fR" 4
 229 .IX Item "directories()"
 230 This takes one mandatory parameter, the name of a module.  It returns a list of
 231 all the directories from the package.  Additional parameters are allowed.  The
 232 first is one of the strings \*(L"prog\*(R", \*(L"doc\*(R" or \*(L"all\*(R", to select either just
 233 program directories, just manual directories or all directories.  The remaining
 234 parameters are a list of directories. The directories returned will be
 235 restricted to those under the specified directories.  This method returns only
 236 the leaf directories that contain files from the specified module.
 237 .IP "\fIdirectory_tree()\fR" 4
 238 .IX Item "directory_tree()"
 239 This is identical in operation to \fIdirectories()\fR, except that it includes all the
 240 intermediate directories back up to the specified directories.
 241 .IP "\fIvalidate()\fR" 4
 242 .IX Item "validate()"
 243 This takes one mandatory parameter, the name of a module.  It checks that all
 244 the files listed in the modules .packlist actually exist, and returns a list of
 245 any missing files.  If an optional second argument which evaluates to true is
 246 given any missing files will be removed from the .packlist
 247 .IP "\fIpacklist()\fR" 4
 248 .IX Item "packlist()"
 249 This returns the ExtUtils::Packlist object for the specified module.
 250 .IP "\fIversion()\fR" 4
 251 .IX Item "version()"
 252 This returns the version number for the specified module.
 253 .SH "EXAMPLE"
 254 .IX Header "EXAMPLE"
 255 See the example in ExtUtils::Packlist.
 256 .SH "AUTHOR"
 257 .IX Header "AUTHOR"
 258 Alan Burlison <Alan.Burlison@uk.sun.com>