view release on metacpan or  search on metacpan

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

dependency-checking semantics are available, except that we also
understand perl's new double-dotted version numbers.

=head2 XS Extensions

Modules which need to compile XS code should list C<ExtUtils::CBuilder>
as a C<build_requires> element.


=head1 SAVING CONFIGURATION INFORMATION

Module::Build provides a very convenient way to save configuration
information that your installed modules (or your regression tests) can
access.  If your Build process calls the C<feature()> or
C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
automatically be created for you, where C<Foo::Bar> is the
C<module_name> parameter as passed to C<new()>.  This module provides
access to the data saved by these methods, and a way to update the
values.  There is also a utility script called C<config_data>
distributed with Module::Build that provides a command line interface
to this same functionality.  See also the generated
C<Foo::Bar::ConfigData> documentation, and the C<config_data>
script's documentation, for more information.


=head1 STARTING MODULE DEVELOPMENT

When starting development on a new module, it's rarely worth your time
to create a tree of all the files by hand.  Some automatic
module-creators are available: the oldest is C<h2xs>, which has
shipped with perl itself for a long time.  Its name reflects the fact
that modules were originally conceived of as a way to wrap up a C
library (thus the C<h> part) into perl extensions (thus the C<xs>
part).

These days, C<h2xs> has largely been superseded by modules like
C<ExtUtils::ModuleMaker>, and C<Module::Starter>.  They have varying
degrees of support for C<Module::Build>.


=head1 AUTOMATION

One advantage of Module::Build is that since it's implemented as Perl
methods, you can invoke these methods directly if you want to install
a module non-interactively.  For instance, the following Perl script
will invoke the entire build/install procedure:

  my $build = Module::Build->new(module_name => 'MyModule');
  $build->dispatch('build');
  $build->dispatch('test');
  $build->dispatch('install');

If any of these steps encounters an error, it will throw a fatal
exception.

You can also pass arguments as part of the build process:

  my $build = Module::Build->new(module_name => 'MyModule');
  $build->dispatch('build');
  $build->dispatch('test', verbose => 1);
  $build->dispatch('install', sitelib => '/my/secret/place/');

Building and installing modules in this way skips creating the
C<Build> script.


=head1 MIGRATION

Note that if you want to provide both a F<Makefile.PL> and a
F<Build.PL> for your distribution, you probably want to add the
following to C<WriteMakefile> in your F<Makefile.PL> so that C<MakeMaker>
doesn't try to run your F<Build.PL> as a normal F<.PL> file:

  PL_FILES => {},

You may also be interested in looking at the C<Module::Build::Compat>
module, which can automatically create various kinds of F<Makefile.PL>
compatibility layers.


=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 SEE ALSO

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

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

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

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

=cut