Provided by: libextutils-installpaths-perl_0.012-1.1_all bug

NAME

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

VERSION

       version 0.012

SYNOPSIS

        use ExtUtils::InstallPaths;
        use ExtUtils::Install 'install';
        GetOptions(\my %opt, 'install_base=s', 'install_path=s%', 'installdirs=s', 'destdir=s', 'prefix=s', 'uninst:1', 'verbose:1');
        my $paths = ExtUtils::InstallPaths->new(%opt, dist_name => $dist_name);
        install($paths->install_map, $opt{verbose}, 0, $opt{uninst});

DESCRIPTION

       This module tries to make install path resolution as easy as possible.

       When you want to install a module, it needs to figure out where to install things. The
       nutshell version of how this works is that default installation locations are determined
       from ExtUtils::Config, and they may be individually overridden by using the "install_path"
       attribute. An "install_base" attribute lets you specify an alternative installation root
       like /home/foo and "prefix" does something similar in a rather different (and more
       complicated) way. "destdir" lets you specify a temporary installation directory like
       /tmp/install in case you want to create bundled-up installable packages.

       The following types are supported by default.

       •   lib

           Usually pure-Perl module files ending in .pm or .pod.

       •   arch

           "Architecture-dependent" module files, usually produced by compiling XS, Inline, or
           similar code.

       •   script

           Programs written in pure Perl.  In order to improve reuse, you may want to make these
           as small as possible - put the code into modules whenever possible.

       •   bin

           "Architecture-dependent" executable programs, i.e. compiled C code or something.
           Pretty rare to see this in a perl distribution, but it happens.

       •   bindoc

           Documentation for the stuff in "script" and "bin".  Usually generated from the POD in
           those files.  Under Unix, these are manual pages belonging to the 'man1' category.
           Unless explicitly set, this is only available on platforms supporting manpages.

       •   libdoc

           Documentation for the stuff in "lib" and "arch".  This is usually generated from the
           POD in .pm and .pod files.  Under Unix, these are manual pages belonging to the 'man3'
           category. Unless explicitly set, this is only available on platforms supporting
           manpages.

       •   binhtml

           This is the same as "bindoc" above, but applies to HTML documents. Unless explicitly
           set, this is only available when perl was configured to do so.

       •   libhtml

           This is the same as "libdoc" above, but applies to HTML documents. Unless explicitly
           set, this is only available when perl was configured to do so.

ATTRIBUTES

   installdirs
       The default destinations for these installable things come from entries in your system's
       configuration. You can select from three different sets of default locations by setting
       the "installdirs" parameter as follows:

                                 'installdirs' set to:
                          core          site                vendor

                     uses the following defaults from ExtUtils::Config:

         lib     => installprivlib  installsitelib      installvendorlib
         arch    => installarchlib  installsitearch     installvendorarch
         script  => installscript   installsitescript   installvendorscript
         bin     => installbin      installsitebin      installvendorbin
         bindoc  => installman1dir  installsiteman1dir  installvendorman1dir
         libdoc  => installman3dir  installsiteman3dir  installvendorman3dir
         binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
         libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]

         * Under some OS (eg. MSWin32) the destination for HTML documents is determined by the C<Config.pm> entry C<installhtmldir>.

       The default value of "installdirs" is "site".

   install_base
       You can also set the whole bunch of installation paths by supplying the "install_base"
       parameter to point to a directory on your system.  For instance, if you set "install_base"
       to "/home/ken" on a Linux system, you'll install as follows:

         lib     => /home/ken/lib/perl5
         arch    => /home/ken/lib/perl5/i386-linux
         script  => /home/ken/bin
         bin     => /home/ken/bin
         bindoc  => /home/ken/man/man1
         libdoc  => /home/ken/man/man3
         binhtml => /home/ken/html
         libhtml => /home/ken/html

   prefix
       This sets a prefix, identical to ExtUtils::MakeMaker's PREFIX option. This does something
       similar to "install_base" in a much more complicated way.

   config()
       The ExtUtils::Config object used for this object.

   verbose
       The verbosity of ExtUtils::InstallPaths. It defaults to 0

   create_packlist
       Together with "module_name" this controls whether a packlist will be added; it defaults to
       1.

   dist_name
       The name of the current module.

   module_name
       The name of the main module of the package. This is required for packlist creation, but in
       the future it may be replaced by dist_name. It defaults to "dist_name =~ s/-/::/gr" if
       dist_name is set.

   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 "rpm" or "dpkg" could create a
       package from), you can use the "destdir" parameter. E.g. Setting "destdir" to "/tmp/foo"
       will effectively install to "/tmp/foo/$sitelib", "/tmp/foo/$sitearch", and the like,
       except that it will use "File::Spec" to make the pathnames work correctly on whatever
       platform you're installing on.

METHODS

   new
       Create a new ExtUtils::InstallPaths object. All attributes are valid arguments to the
       constructor, as well as this:

       •   install_path

           This must be a hashref with the type as keys and the destination as values.

       •   install_base_relpaths

           This must be a hashref with types as keys and a path relative to the install_base as
           value.

       •   prefix_relpaths

           This must be a hashref any of these three keys: core, vendor, site. Each of the values
           mush be a hashref with types as keys and a path relative to the prefix as value. You
           probably want to make these three hashrefs identical.

       •   original_prefix

           This must be a hashref with the legal installdirs values as keys and the prefix
           directories as values.

       •   install_sets

           This mush be a hashref with the legal installdirs are keys, and the values being
           hashrefs with types as keys and locations as values.

   install_map()
       Return a map suitable for use with ExtUtils::Install. In most cases, this is the only
       method you'll need.

   install_destination($type)
       Returns the destination of a certain type.

   install_types()
       Return a list of all supported install types in the current configuration.

   is_default_installable($type)
       Given a file type, will return true if the file type would normally be installed when
       neither install-base nor prefix has been set.  I.e. it will be true only if the path is
       set from the configuration object or set explicitly by the user via install_path.

   install_path($type)
       Gets the install path for a certain type.

   install_sets($installdirs, $type)
       Get the path for a certain $type with a certain $installdirs.

   install_base_relpaths($type, $relpath)
       Get the relative paths for use with install_base for a certain type.

   prefix_relative($installdirs, $type)
       Gets the path of a certain $type and $installdirs relative to the prefix.

   prefix_relpaths($install_dirs, $type)
       Get the default relative path to use in case the config install paths cannot be
       prefixified. You do not want to use this to get any relative path, but may require it to
       set it for custom types.

   original_prefix($installdirs)
       Get the original prefix for a certain type of $installdirs.

SEE ALSO

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

AUTHORS

       •   Ken Williams <kwilliams@cpan.org>

       •   Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Ken Williams, Leon Timmermans.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.