[Module-build-general] [comments please] module installation paths
Status: Beta
Brought to you by:
kwilliams
|
From: Ken W. <ke...@ma...> - 2003-06-30 17:11:53
|
Hi all,
I've decided on some semantics for how to specify installation paths
using Module::Build. Here's the POD I've written for it, please give
me feedback if you have any.
Thanks.
-Ken
-----------------------------------------------------------
=head2 How Installation Works
When you invoke Module::Build's C<build> action, it needs to figure
out where to install things. The nutshell version of how this works
is that default installation locations are determined from
F<Config.pm>, and they may be overridden by using the C<install_path>
parameter. An C<install_base> parameter lets you specify an
alternative installation root like F</home/foo>, and a C<destdir> lets
you specify a temporary installation directory like F</tmp/install> in
case you want to create bundled-up installable packages.
Natively, Module::Build provides default installation locations for
the following types of installable items:
=over 4
=item lib
Usually pure-Perl module files ending in F<.pm>.
=item arch
"Architecture-dependent" module files, usually produced by compiling
XS, Inline, or similar code.
=item script
Programs written in pure Perl. Try to make these as small as possible
- put the code into modules whenever possible.
=item bin
"Architecture-dependent" programs, i.e. compiled C code or something.
Pretty rare to see this in a perl distribution, but it happens.
=item libdoc
Documentation for the stuff in C<lib> and C<arch>. This is usually
generated from the POD in F<.pm> files. Under Unix, these are manual
pages belonging to the 'man3' category.
=item bindoc
Documentation for the stuff in C<script> and C<bin>. Usually
generated from the POD in those files. Under Unix, these are manual
pages belonging to the 'man1' category.
=back
The default destinations for these installable things come from
entries in your system's C<Config.pm>. You can select from three
different sets of default locations by setting the C<installdirs>
parameter as follows:
'installdirs' set to:
core site vendor
uses the following defaults from Config.pm:
lib => installprivlib installsitelib installvendorlib
arch => installarchlib installsitearch installvendorarch
script => installscript installsitebin installvendorbin
bin => installbin installsitebin installvendorbin
libdoc => installman3dir installsiteman3dir installvendorman3dir
bindoc => installman1dir installsiteman1dir installvendorman1dir
(Note that the 'script' line is different from MakeMaker -
unfortunately there's no such thing as "installsitescript" or
"installvendorscript" entry in C<Config.pm>, so we use the
"installsitebin" and "installvendorbin" entries to at least get the
general location right. In the future, if C<Config.pm> adds some more
appropriate entries, we'll start using those.)
=item install_path
Once the defaults have been set, you can override them. You can set
individual entries by using the C<install_path> parameter:
my $m = Module::Build->new
(...other options...,
install_path => {lib => '/foo/lib',
arch => '/foo/lib/arch'});
On the command line, that would look like this:
perl Build.PL install_path=lib=/foo/lib install_path=arch=/foo/lib/arch
or this:
Build install install_path=lib=/foo/lib install_path=arch=/foo/lib/arch
=item install_base
You can also set the whole bunch of installation paths by supplying the
C<install_base> parameter to point to a directory on your system. For
instance, if you set C<install_base> to "/home/ken" on a Linux
system, you'll install as follows:
lib => /home/ken/lib
arch => /home/ken/lib/i386-linux
script => /home/ken/scripts
bin => /home/ken/bin
libdoc => /home/ken/man/man1
bindoc => /home/ken/man/man3
Note that this is I<different> from how MakeMaker's C<PREFIX>
parameter works. C<PREFIX> tries to create a mini-replica of a
C<site>-style installation under the directory you specify, which is
not always possible (and the results are not always pretty in this
case). C<install_base> just gives you a default layout under the
directory you specify, which may have little to do with the
C<installdirs=site> layout.
The exact layout under the directory you specify may vary by system -
we try to do the "sensible" thing on each platform.
=item destdir
If you want to install everything into a temporary directory first
(for instance, if you want to create a directory tree that a package
manager like C<rpm> or C<dpkg> could create a package from), you can
use the C<destdir> parameter:
perl Build.PL destdir=/tmp/foo
or
Build install destdir=/tmp/foo
This will effectively install to "$destdir/$sitelib",
"$destdir/$sitearch", and the like, except that it will use
C<File::Spec> to make the pathnames work correctly on whatever
platform you're installing on.
=item uninst
If you want the installation process to look around in C<@INC> for
other versions of the stuff you're installing and try to delete it,
you can use the C<uninst> parameter, which tells C<Module::Install> to
do so:
Build install uninst=1
This can be a good idea, as it helps prevent multiple versions of a
module from being present on your system, which can be a confusing
situation indeed.
=back
|