1ExtUtils::InstallPaths(U3s)er Contributed Perl DocumentatEixotnUtils::InstallPaths(3)
2
6 ExtUtils::InstallPaths - Build.PL install path logic made easy
7
9 version 0.012
10
12 use ExtUtils::InstallPaths;
13 use ExtUtils::Install 'install';
14 GetOptions(\my %opt, 'install_base=s', 'install_path=s%', 'installdirs=s', 'destdir=s', 'prefix=s', 'uninst:1', 'verbose:1');
15 my $paths = ExtUtils::InstallPaths->new(%opt, dist_name => $dist_name);
16 install($paths->install_map, $opt{verbose}, 0, $opt{uninst});
17
19 This module tries to make install path resolution as easy as possible.
20 When you want to install a module, it needs to figure out where to
22 install things. The nutshell version of how this works is that default
23 installation locations are determined from ExtUtils::Config, and they
24 may be individually overridden by using the "install_path" attribute.
25 An "install_base" attribute lets you specify an alternative
26 installation root like /home/foo and "prefix" does something similar in
27 a rather different (and more complicated) way. "destdir" lets you
28 specify a temporary installation directory like /tmp/install in case
29 you want to create bundled-up installable packages.
30 The following types are supported by default.
32 • lib
34 Usually pure-Perl module files ending in .pm or .pod.
36 • arch
38 "Architecture-dependent" module files, usually produced by
40 compiling XS, Inline, or similar code.
41 • script
43 Programs written in pure Perl. In order to improve reuse, you may
45 want to make these as small as possible - put the code into modules
46 whenever possible.
47 • bin
49 "Architecture-dependent" executable programs, i.e. compiled C code
51 or something. Pretty rare to see this in a perl distribution, but
52 it happens.
53 • bindoc
55 Documentation for the stuff in "script" and "bin". Usually
57 generated from the POD in those files. Under Unix, these are
58 manual pages belonging to the 'man1' category. Unless explicitly
59 set, this is only available on platforms supporting manpages.
60 • libdoc
62 Documentation for the stuff in "lib" and "arch". This is usually
64 generated from the POD in .pm and .pod files. Under Unix, these
65 are manual pages belonging to the 'man3' category. Unless
66 explicitly set, this is only available on platforms supporting
67 manpages.
68 • binhtml
70 This is the same as "bindoc" above, but applies to HTML documents.
72 Unless explicitly set, this is only available when perl was
73 configured to do so.
74 • libhtml
76 This is the same as "libdoc" above, but applies to HTML documents.
78 Unless explicitly set, this is only available when perl was
79 configured to do so.
80
82 installdirs
83 The default destinations for these installable things come from entries
84 in your system's configuration. You can select from three different
85 sets of default locations by setting the "installdirs" parameter as
86 follows:
87 'installdirs' set to:
89 core site vendor
90 uses the following defaults from ExtUtils::Config:
92 lib => installprivlib installsitelib installvendorlib
94 arch => installarchlib installsitearch installvendorarch
95 script => installscript installsitescript installvendorscript
96 bin => installbin installsitebin installvendorbin
97 bindoc => installman1dir installsiteman1dir installvendorman1dir
98 libdoc => installman3dir installsiteman3dir installvendorman3dir
99 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
100 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
101 * Under some OS (eg. MSWin32) the destination for HTML documents is determined by the C<Config.pm> entry C<installhtmldir>.
103 The default value of "installdirs" is "site".
105 install_base
107 You can also set the whole bunch of installation paths by supplying the
108 "install_base" parameter to point to a directory on your system. For
109 instance, if you set "install_base" to "/home/ken" on a Linux system,
110 you'll install as follows:
111 lib => /home/ken/lib/perl5
113 arch => /home/ken/lib/perl5/i386-linux
114 script => /home/ken/bin
115 bin => /home/ken/bin
116 bindoc => /home/ken/man/man1
117 libdoc => /home/ken/man/man3
118 binhtml => /home/ken/html
119 libhtml => /home/ken/html
120 prefix
122 This sets a prefix, identical to ExtUtils::MakeMaker's PREFIX option.
123 This does something similar to "install_base" in a much more
124 complicated way.
125 config()
127 The ExtUtils::Config object used for this object.
128 verbose
130 The verbosity of ExtUtils::InstallPaths. It defaults to 0
131 create_packlist
133 Together with "module_name" this controls whether a packlist will be
134 added; it defaults to 1.
135 dist_name
137 The name of the current module.
138 module_name
140 The name of the main module of the package. This is required for
141 packlist creation, but in the future it may be replaced by dist_name.
142 It defaults to "dist_name =~ s/-/::/gr" if dist_name is set.
143 destdir
145 If you want to install everything into a temporary directory first (for
146 instance, if you want to create a directory tree that a package manager
147 like "rpm" or "dpkg" could create a package from), you can use the
148 "destdir" parameter. E.g. Setting "destdir" to "/tmp/foo" will
149 effectively install to "/tmp/foo/$sitelib", "/tmp/foo/$sitearch", and
150 the like, except that it will use "File::Spec" to make the pathnames
151 work correctly on whatever platform you're installing on.
152
154 new
155 Create a new ExtUtils::InstallPaths object. All attributes are valid
156 arguments to the constructor, as well as this:
157 • install_path
159 This must be a hashref with the type as keys and the destination as
161 values.
162 • install_base_relpaths
164 This must be a hashref with types as keys and a path relative to
166 the install_base as value.
167 • prefix_relpaths
169 This must be a hashref any of these three keys: core, vendor, site.
171 Each of the values mush be a hashref with types as keys and a path
172 relative to the prefix as value. You probably want to make these
173 three hashrefs identical.
174 • original_prefix
176 This must be a hashref with the legal installdirs values as keys
178 and the prefix directories as values.
179 • install_sets
181 This mush be a hashref with the legal installdirs are keys, and the
183 values being hashrefs with types as keys and locations as values.
184 install_map()
186 Return a map suitable for use with ExtUtils::Install. In most cases,
187 this is the only method you'll need.
188 install_destination($type)
190 Returns the destination of a certain type.
191 install_types()
193 Return a list of all supported install types in the current
194 configuration.
195 is_default_installable($type)
197 Given a file type, will return true if the file type would normally be
198 installed when neither install-base nor prefix has been set. I.e. it
199 will be true only if the path is set from the configuration object or
200 set explicitly by the user via install_path.
201 install_path($type)
203 Gets the install path for a certain type.
204 install_sets($installdirs, $type)
206 Get the path for a certain $type with a certain $installdirs.
207 install_base_relpaths($type, $relpath)
209 Get the relative paths for use with install_base for a certain type.
210 prefix_relative($installdirs, $type)
212 Gets the path of a certain $type and $installdirs relative to the
213 prefix.
214 prefix_relpaths($install_dirs, $type)
216 Get the default relative path to use in case the config install paths
217 cannot be prefixified. You do not want to use this to get any relative
218 path, but may require it to set it for custom types.
219 original_prefix($installdirs)
221 Get the original prefix for a certain type of $installdirs.
222
224 • Build.PL spec <http://github.com/dagolden/cpan-api-
225 buildpl/blob/master/lib/CPAN/API/BuildPL.pm>
226
228 • Ken Williams <kwilliams@cpan.org>
229 • Leon Timmermans <leont@cpan.org>
231
233 This software is copyright (c) 2011 by Ken Williams, Leon Timmermans.
234 This is free software; you can redistribute it and/or modify it under
236 the same terms as the Perl 5 programming language system itself.
237perl v5.36.0 2023-01-20 ExtUtils::InstallPaths(3)