view release on metacpan or  search on metacpan

local/lib/perl5/Module/Build.pm  view on Meta::CPAN

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.

=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 binhtml

This is the same as C<bindoc> above, but applies to HTML documents.

=item libhtml

This is the same as C<libdoc> above, but applies to HTML documents.

=back

Four other parameters let you control various aspects of how
installation paths are determined:

=over 4

=item installdirs

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   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 C<installdirs> is "site".  If you're creating
vendor distributions of module packages, you may want to do something
like this:

  perl Build.PL --installdirs vendor

or

  ./Build install --installdirs vendor

If you're installing an updated version of a module that was included
with perl itself (i.e. a "core module"), then you may set
C<installdirs> to "core" to overwrite the module in its present
location.

(Note that the 'script' line is different from C<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.

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/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

Note that this is I<different> from how C<MakeMaker>'s C<PREFIX>
parameter works.  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 "/tmp/foo/$sitelib",
"/tmp/foo/$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 prefix

Provided for compatibility with C<ExtUtils::MakeMaker>'s PREFIX argument.
C<prefix> should be used when you want Module::Build to install your
modules, documentation, and scripts in the same place as
C<ExtUtils::MakeMaker>'s PREFIX mechanism.

The following are equivalent.

    perl Build.PL --prefix /tmp/foo
    perl Makefile.PL PREFIX=/tmp/foo

Because of the complex nature of the prefixification logic, the
behavior of PREFIX in C<MakeMaker> has changed subtly over time.
Module::Build's --prefix logic is equivalent to the PREFIX logic found
in C<ExtUtils::MakeMaker> 6.30.

The maintainers of C<MakeMaker> do understand the troubles with the
PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of
C<MakeMaker>, which was released in 2006.

If you don't need to retain compatibility with old versions (pre-6.31) of C<ExtUtils::MakeMaker> or
are starting a fresh Perl installation we recommend you use
C<install_base> instead (and C<INSTALL_BASE> in C<ExtUtils::MakeMaker>).
See L<Module::Build::Cookbook/Installing in the same location as
ExtUtils::MakeMaker> for further information.


=back


=head1 COMPARISON

A comparison between C<Module::Build> and other CPAN distribution installers.

=over

=item *

L<ExtUtils::MakeMaker> requires C<make> and use of a F<Makefile>.
C<Module::Build> does not, nor do other pure-perl installers following the
F<Build.PL> spec such as L<Module::Build::Tiny>. In practice, this is usually
not an issue for the end user, as C<make> is already required to install most
CPAN modules, even on Windows.

=item *

L<ExtUtils::MakeMaker> has been a core module in every version of Perl 5, and
must maintain compatibility to install the majority of CPAN modules.
C<Module::Build> was added to core in Perl 5.10 and removed from core in Perl
5.20, and (like L<ExtUtils::MakeMaker>) is only updated to fix critical issues
and maintain compatibility. C<Module::Build> and other non-core installers like
L<Module::Build::Tiny> are installed from CPAN by declaring themselves as a
C<configure> phase prerequisite, and in this way any installer can be used in
place of L<ExtUtils::MakeMaker>.

=item *

Customizing the build process with L<ExtUtils::MakeMaker> involves overriding
certain methods that form the F<Makefile> by defining the subs in the C<MY::>
namespace, requiring in-depth knowledge of F<Makefile>, but allowing targeted
customization of the entire build. Customizing C<Module::Build> involves
subclassing C<Module::Build> itself, adding or overriding pure-perl methods
that represent build actions, which are invoked as arguments passed to the
generated C<./Build> script. This is a simpler concept but requires redefining
the standard build actions to invoke your customizations.
L<Module::Build::Tiny> does not allow for customization.

=item *

C<Module::Build> provides more features and a better experience for distribution
authors than L<ExtUtils::MakeMaker>. However, tools designed specifically for
authoring, such as L<Dist::Zilla> and its spinoffs L<Dist::Milla> and
L<Minilla>, provide these features and more, and generate a configure script
(F<Makefile.PL>/F<Build.PL>) that will use any of the various installers
separately on the end user side. L<App::ModuleBuildTiny> is an alternative
standalone authoring tool for distributions using L<Module::Build::Tiny>, which
requires only a simple two-line F<Build.PL>.

=back


=head1 TO DO

The current method of relying on time stamps to determine whether a
derived file is out of date isn't likely to scale well, since it
requires tracing all dependencies backward, it runs into problems on
NFS, and it's just generally flimsy.  It would be better to use an MD5
signature or the like, if available.  See C<cons> for an example.

 - append to perllocal.pod
 - add a 'plugin' functionality


=head1 AUTHOR

Ken Williams <kwilliams@cpan.org>

Development questions, bug reports, and patches should be sent to the
Module-Build mailing list at <module-build@perl.org>.

Bug reports are also welcome at
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.

The latest development version is available from the Git
repository at <https://github.com/Perl-Toolchain-Gang/Module-Build>


=head1 COPYRIGHT

Copyright (c) 2001-2006 Ken Williams.  All rights reserved.