From 467298a34215401cdcbb1dded51bc2aba5f1f41c Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Thu, 11 Jun 2015 22:32:06 +0000 Subject: Module-Build-0.4214 --- lib/Module/Build/Authoring.pod | 326 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 lib/Module/Build/Authoring.pod (limited to 'lib/Module/Build/Authoring.pod') diff --git a/lib/Module/Build/Authoring.pod b/lib/Module/Build/Authoring.pod new file mode 100644 index 0000000..a32b31e --- /dev/null +++ b/lib/Module/Build/Authoring.pod @@ -0,0 +1,326 @@ +=head1 NAME + +Module::Build::Authoring - Authoring Module::Build modules + +=head1 DESCRIPTION + +When creating a C script for a module, something like the +following code will typically be used: + + use Module::Build; + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + license => 'perl', + requires => { + 'perl' => '5.6.1', + 'Some::Module' => '1.23', + 'Other::Module' => '>= 1.2, != 1.5, < 2.0', + }, + ); + $build->create_build_script; + +A simple module could get away with something as short as this for its +C script: + + use Module::Build; + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +The model used by C is a lot like the C +metaphor, with the following correspondences: + + In Module::Build In ExtUtils::MakeMaker + --------------------------- ------------------------ + Build.PL (initial script) Makefile.PL (initial script) + Build (a short perl script) Makefile (a long Makefile) + _build/ (saved state info) various config text in the Makefile + +Any customization can be done simply by subclassing C +and adding a method called (for example) C, overriding +the default 'test' action. You could also add a method called +C, and then you could perform the action C. + +For information on providing compatibility with +C, see L and +L. + + +=head1 STRUCTURE + +Module::Build creates a class hierarchy conducive to customization. +Here is the parent-child class hierarchy in classy ASCII art: + + /--------------------\ + | Your::Parent | (If you subclass Module::Build) + \--------------------/ + | + | + /--------------------\ (Doesn't define any functionality + | Module::Build | of its own - just figures out what + \--------------------/ other modules to load.) + | + | + /-----------------------------------\ (Some values of $^O may + | Module::Build::Platform::$^O | define specialized functionality. + \-----------------------------------/ Otherwise it's ...::Default, a + | pass-through class.) + | + /--------------------------\ + | Module::Build::Base | (Most of the functionality of + \--------------------------/ Module::Build is defined here.) + + +=head1 SUBCLASSING + +Right now, there are two ways to subclass Module::Build. The first +way is to create a regular module (in a C<.pm> file) that inherits +from Module::Build, and use that module's class instead of using +Module::Build directly: + + ------ in Build.PL: ---------- + #!/usr/bin/perl + + use lib q(/nonstandard/library/path); + use My::Builder; # Or whatever you want to call it + + my $build = My::Builder->new + ( + module_name => 'Foo::Bar', # All the regular args... + license => 'perl', + dist_author => 'A N Other ', + requires => { Carp => 0 } + ); + $build->create_build_script; + +This is relatively straightforward, and is the best way to do things +if your My::Builder class contains lots of code. The +C method will ensure that the current value of +C<@INC> (including the C) is propagated to +the Build script, so that My::Builder can be found when running build +actions. If you find that you need to C into a different directories +in your subclass methods or actions, be sure to always return to the original +directory (available via the C method) before returning control +to the parent class. This is important to avoid data serialization problems. + +For very small additions, Module::Build provides a C +method that lets you subclass Module::Build more conveniently, without +creating a separate file for your module: + + ------ in Build.PL: ---------- + #!/usr/bin/perl + + use Module::Build; + my $class = Module::Build->subclass + ( + class => 'My::Builder', + code => q{ + sub ACTION_foo { + print "I'm fooing to death!\n"; + } + }, + ); + + my $build = $class->new + ( + module_name => 'Foo::Bar', # All the regular args... + license => 'perl', + dist_author => 'A N Other ', + requires => { Carp => 0 } + ); + $build->create_build_script; + +Behind the scenes, this actually does create a C<.pm> file, since the +code you provide must persist after Build.PL is run if it is to be +very useful. + +See also the documentation for the L +method. + + +=head1 PREREQUISITES + +=head2 Types of prerequisites + +To specify what versions of other modules are used by this +distribution, several types of prerequisites can be defined with the +following parameters: + +=over 3 + +=item configure_requires + +Items that must be installed I configuring this distribution +(i.e. before running the F script). This might be a +specific minimum version of C or any other module the +F needs in order to do its stuff. Clients like C +or C will be expected to pick C out of the +F file and install these items before running the +C. + +If no configure_requires is specified, the current version of Module::Build +is automatically added to configure_requires. + +=item build_requires + +Items that are necessary for building and testing this distribution, +but aren't necessary after installation. This can help users who only +want to install these items temporarily. It also helps reduce the +size of the CPAN dependency graph if everything isn't smooshed into +C. + +=item requires + +Items that are necessary for basic functioning. + +=item recommends + +Items that are recommended for enhanced functionality, but there are +ways to use this distribution without having them installed. You +might also think of this as "can use" or "is aware of" or "changes +behavior in the presence of". + +=item test_requires + +Items that are necessary for testing. + +=item conflicts + +Items that can cause problems with this distribution when installed. +This is pretty rare. + +=back + +=head2 Format of prerequisites + +The prerequisites are given in a hash reference, where the keys are +the module names and the values are version specifiers: + + requires => { + Foo::Module => '2.4', + Bar::Module => 0, + Ken::Module => '>= 1.2, != 1.5, < 2.0', + perl => '5.6.0' + }, + +The above four version specifiers have different effects. The value +C<'2.4'> means that B version 2.4 of C must be +installed. The value C<0> means that B version of C +is acceptable, even if C doesn't define a version. The +more verbose value C<'E= 1.2, != 1.5, E 2.0'> means that +C's version must be B 1.2, B 2.0, +and B 1.5. The list of criteria is separated by commas, +and all criteria must be satisfied. + +A special C entry lets you specify the versions of the Perl +interpreter that are supported by your module. The same version +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 +as a C 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 or +C methods, then a C module will +automatically be created for you, where C is the +C parameter as passed to C. 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 +distributed with Module::Build that provides a command line interface +to this same functionality. See also the generated +C documentation, and the C +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, 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 part) into perl extensions (thus the C +part). + +These days, C has largely been superseded by modules like +C, and C. They have varying +degrees of support for C. + + +=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 script. + + +=head1 MIGRATION + +Note that if you want to provide both a F and a +F for your distribution, you probably want to add the +following to C in your F so that C +doesn't try to run your F as a normal F<.PL> file: + + PL_FILES => {}, + +You may also be interested in looking at the C +module, which can automatically create various kinds of F +compatibility layers. + + +=head1 AUTHOR + +Ken Williams + +Development questions, bug reports, and patches should be sent to the +Module-Build mailing list at . + +Bug reports are also welcome at +. + +The latest development version is available from the Git +repository at + + +=head1 SEE ALSO + +perl(1), L(3), L(3), +L(3), L(3), L(3) + +F Specification: +L + +L + +L + +=cut -- cgit v1.2.1