javonet-ruby-sdk 2.5.14 → 2.5.15

data/lib/javonet-ruby-sdk/Binaries/Perl/Linux/X64/deps/lib/perl5/Module/Build/Authoring.pod

@@ -1,326 +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 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<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/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