1ExtUtils::InstallPaths(U3s)er Contributed Perl DocumentatEixotnUtils::InstallPaths(3)
2
3
4

NAME

6       ExtUtils::InstallPaths - Build.PL install path logic made easy
7

VERSION

9       version 0.012
10

SYNOPSIS

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

DESCRIPTION

19       This module tries to make install path resolution as easy as possible.
20
21       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
31       The following types are supported by default.
32
33       •   lib
34
35           Usually pure-Perl module files ending in .pm or .pod.
36
37       •   arch
38
39           "Architecture-dependent" module files, usually produced by
40           compiling XS, Inline, or similar code.
41
42       •   script
43
44           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
48       •   bin
49
50           "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
54       •   bindoc
55
56           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
61       •   libdoc
62
63           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
69       •   binhtml
70
71           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
75       •   libhtml
76
77           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

ATTRIBUTES

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
88                                 'installdirs' set to:
89                          core          site                vendor
90
91                     uses the following defaults from ExtUtils::Config:
92
93         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
102         * Under some OS (eg. MSWin32) the destination for HTML documents is determined by the C<Config.pm> entry C<installhtmldir>.
103
104       The default value of "installdirs" is "site".
105
106   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
112         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
121   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
126   config()
127       The ExtUtils::Config object used for this object.
128
129   verbose
130       The verbosity of ExtUtils::InstallPaths. It defaults to 0
131
132   create_packlist
133       Together with "module_name" this controls whether a packlist will be
134       added; it defaults to 1.
135
136   dist_name
137       The name of the current module.
138
139   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
144   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

METHODS

154   new
155       Create a new ExtUtils::InstallPaths object. All attributes are valid
156       arguments to the constructor, as well as this:
157
158       •   install_path
159
160           This must be a hashref with the type as keys and the destination as
161           values.
162
163       •   install_base_relpaths
164
165           This must be a hashref with types as keys and a path relative to
166           the install_base as value.
167
168       •   prefix_relpaths
169
170           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
175       •   original_prefix
176
177           This must be a hashref with the legal installdirs values as keys
178           and the prefix directories as values.
179
180       •   install_sets
181
182           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
185   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
189   install_destination($type)
190       Returns the destination of a certain type.
191
192   install_types()
193       Return a list of all supported install types in the current
194       configuration.
195
196   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
202   install_path($type)
203       Gets the install path for a certain type.
204
205   install_sets($installdirs, $type)
206       Get the path for a certain $type with a certain $installdirs.
207
208   install_base_relpaths($type, $relpath)
209       Get the relative paths for use with install_base for a certain type.
210
211   prefix_relative($installdirs, $type)
212       Gets the path of a certain $type and $installdirs relative to the
213       prefix.
214
215   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
220   original_prefix($installdirs)
221       Get the original prefix for a certain type of $installdirs.
222

SEE ALSO

224       •   Build.PL spec <http://github.com/dagolden/cpan-api-
225           buildpl/blob/master/lib/CPAN/API/BuildPL.pm>
226

AUTHORS

228       •   Ken Williams <kwilliams@cpan.org>
229
230       •   Leon Timmermans <leont@cpan.org>
231
233       This software is copyright (c) 2011 by Ken Williams, Leon Timmermans.
234
235       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.
237
238
239
240perl v5.36.0                      2023-01-20         ExtUtils::InstallPaths(3)
Impressum