view release on metacpan or  search on metacpan

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

To install C<Module::Build>, and any other module that uses
C<Module::Build> for its installation process, do the following:

  perl Build.PL       # 'Build.PL' script creates the 'Build' script
  ./Build             # Need ./ to ensure we're using this "Build" script
  ./Build test        # and not another one that happens to be in the PATH
  ./Build install

This illustrates initial configuration and the running of three
'actions'.  In this case the actions run are 'build' (the default
action), 'test', and 'install'.  Other actions defined so far include:

  build                          manifest
  clean                          manifest_skip
  code                           manpages
  config_data                    pardist
  diff                           ppd
  dist                           ppmdist
  distcheck                      prereq_data
  distclean                      prereq_report
  distdir                        pure_install
  distinstall                    realclean
  distmeta                       retest
  distsign                       skipcheck
  disttest                       test
  docs                           testall
  fakeinstall                    testcover
  help                           testdb
  html                           testpod
  install                        testpodcoverage
  installdeps                    versioninstall

You can run the 'help' action for a complete list of actions.


=head1 GUIDE TO DOCUMENTATION

The documentation for C<Module::Build> is broken up into sections:

=over

=item General Usage (L<Module::Build>)

This is the document you are currently reading. It describes basic
usage and background information.  Its main purpose is to assist the
user who wants to learn how to invoke and control C<Module::Build>
scripts at the command line.

=item Authoring Reference (L<Module::Build::Authoring>)

This document describes the structure and organization of
C<Module::Build>, and the relevant concepts needed by authors who are
writing F<Build.PL> scripts for a distribution or controlling
C<Module::Build> processes programmatically.

=item API Reference (L<Module::Build::API>)

This is a reference to the C<Module::Build> API.

=item Cookbook (L<Module::Build::Cookbook>)

This document demonstrates how to accomplish many common tasks.  It
covers general command line usage and authoring of F<Build.PL>
scripts.  Includes working examples.

=back


=head1 ACTIONS

There are some general principles at work here.  First, each task when
building a module is called an "action".  These actions are listed
above; they correspond to the building, testing, installing,
packaging, etc., tasks.

Second, arguments are processed in a very systematic way.  Arguments
are always key=value pairs.  They may be specified at C<perl Build.PL>
time (i.e. C<perl Build.PL destdir=/my/secret/place>), in which case
their values last for the lifetime of the C<Build> script.  They may
also be specified when executing a particular action (i.e.
C<Build test verbose=1>), in which case their values last only for the
lifetime of that command.  Per-action command line parameters take
precedence over parameters specified at C<perl Build.PL> time.

The build process also relies heavily on the C<Config.pm> module.
If the user wishes to override any of the
values in C<Config.pm>, she may specify them like so:

  perl Build.PL --config cc=gcc --config ld=gcc

The following build actions are provided by default.

=over 4

=item build

[version 0.01]

If you run the C<Build> script without any arguments, it runs the
C<build> action, which in turn runs the C<code> and C<docs> actions.

This is analogous to the C<MakeMaker> I<make all> target.

=item clean

[version 0.01]

This action will clean up any files that the build process may have
created, including the C<blib/> directory (but not including the
C<_build/> directory and the C<Build> script itself).

=item code

[version 0.20]

This action builds your code base.

By default it just creates a C<blib/> directory and copies any C<.pm>
and C<.pod> files from your C<lib/> directory into the C<blib/>
directory.  It also compiles any C<.xs> files from C<lib/> and places

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

  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.

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


=head1 SEE ALSO

perl(1), L<Module::Build::Cookbook>, L<Module::Build::Authoring>,
L<Module::Build::API>, L<ExtUtils::MakeMaker>

F<META.yml> Specification:
L<CPAN::Meta::Spec>

L<http://www.dsmit.com/cons/>

L<http://search.cpan.org/dist/PerlBuildSystem/>

=cut