[Module-build-general] [comments please] module installation paths

[Ken W. <ke...@ma...>]

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