diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod b/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod deleted file mode 100644 index 92164df9211..00000000000 --- a/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod +++ /dev/null @@ -1,322 +0,0 @@ -=head1 NAME - -Module::Build::Authoring - Authoring Module::Build modules - -=head1 DESCRIPTION - -When creating a C<Build.PL> 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<Build.PL> script: - - use Module::Build; - Module::Build->new( - module_name => 'Foo::Bar', - license => 'perl', - )->create_build_script; - -The model used by C<Module::Build> is a lot like the C<MakeMaker> -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<Module::Build> -and adding a method called (for example) C<ACTION_test>, overriding -the default 'test' action. You could also add a method called -C<ACTION_whatever>, and then you could perform the action C<Build -whatever>. - -For information on providing compatibility with -C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and -L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>. - - -=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 <me@here.net.au>', - 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<create_build_script()> method will ensure that the current value of -C<@INC> (including the C</nonstandard/library/path>) 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<chdir> into a different directories -in your subclass methods or actions, be sure to always return to the original -directory (available via the C<base_dir()> 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<subclass()> -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 <me@here.net.au>', - 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<Module::Build::API/"subclass()"> -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<before> configuring this distribution -(i.e. before running the F<Build.PL> script). This might be a -specific minimum version of C<Module::Build> or any other module the -F<Build.PL> needs in order to do its stuff. Clients like C<CPAN.pm> -or C<CPANPLUS> will be expected to pick C<configure_requires> out of the -F<META.yml> file and install these items before running the -C<Build.PL>. - -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<requires>. - -=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 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<at least> version 2.4 of C<Foo::Module> must be -installed. The value C<0> means that B<any> version of C<Bar::Module> -is acceptable, even if C<Bar::Module> doesn't define a version. The -more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that -C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0, -and B<not equal to> 1.5. The list of criteria is separated by commas, -and all criteria must be satisfied. - -A special C<perl> 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<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/dagolden/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 |