summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod322
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