api.pod

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

=head1 NAME

Module::Build::API - API Reference for Module Authors


=head1 DESCRIPTION

I list here some of the most important methods in C<Module::Build>.
Normally you won't need to deal with these methods unless you want to
subclass C<Module::Build>.  But since one of the reasons I created
this module in the first place was so that subclassing is possible
(and easy), I will certainly write more docs as the interface
stabilizes.


=head2 CONSTRUCTORS

=over 4

=item current()

[version 0.20]

This method returns a reasonable facsimile of the currently-executing
C<Module::Build> object representing the current build.  You can use
this object to query its L</notes()> method, inquire about installed
modules, and so on.  This is a great way to share information between
different parts of your build process.  For instance, you can ask
the user a question during C<perl Build.PL>, then use their answer
during a regression test:

  # In Build.PL:
  my $color = $build->prompt("What is your favorite color?");
  $build->notes(color => $color);

  # In t/colortest.t:
  use Module::Build;
  my $build = Module::Build->current;
  my $color = $build->notes('color');
  ...

The way the C<current()> method is currently implemented, there may be
slight differences between the C<$build> object in Build.PL and the
one in C<t/colortest.t>.  It is our goal to minimize these differences
in future releases of Module::Build, so please report any anomalies
you find.

One important caveat: in its current implementation, C<current()> will
B<NOT> work correctly if you have changed out of the directory that
C<Module::Build> was invoked from.

=item new()

[version 0.03]

Creates a new Module::Build object.  Arguments to the new() method are
listed below.  Most arguments are optional, but you must provide
either the L</module_name> argument, or L</dist_name> and one of
L</dist_version> or L</dist_version_from>.  In other words, you must
provide enough information to determine both a distribution name and
version.


=over 4

=item add_to_cleanup

[version 0.19]

An array reference of files to be cleaned up when the C<clean> action
is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)">
method.

=item auto_features

[version 0.26]

This parameter supports the setting of features (see
L</feature($name)>) automatically based on a set of prerequisites.  For
instance, for a module that could optionally use either MySQL or
PostgreSQL databases, you might use C<auto_features> like this:

  my $build = Module::Build->new
    (
     ...other stuff here...
     auto_features => {
       pg_support    => {
                         description => "Interface with Postgres databases",
                         requires    => { 'DBD::Pg' => 23.3,
                                          'DateTime::Format::Pg' => 0 },
                        },
       mysql_support => {
                         description => "Interface with MySQL databases",
                         requires    => { 'DBD::mysql' => 17.9,
                                          'DateTime::Format::MySQL' => 0 },
                        },
     }
    );

For each feature named, the required prerequisites will be checked, and
if there are no failures, the feature will be enabled (set to C<1>).
Otherwise the failures will be displayed to the user and the feature
will be disabled (set to C<0>).

See the documentation for L</requires> for the details of how
requirements can be specified.

=item autosplit

[version 0.04]

An optional C<autosplit> argument specifies a file which should be run
through the L<AutoSplit::autosplit()|AutoSplit/autosplit> function.
If multiple files should be split, the argument may be given as an
array of the files to split.

In general I don't consider autosplitting a great idea, because it's
not always clear that autosplitting achieves its intended performance
benefits.  It may even harm performance in environments like mod_perl,
where as much as possible of a module's code should be loaded during
startup.

=item build_class

[version 0.28]

The Module::Build class or subclass to use in the build script.
Defaults to "Module::Build" or the class name passed to or created by
a call to L</subclass()>.  This property is useful if you're
writing a custom Module::Build subclass and have a bootstrapping
problem--that is, your subclass requires modules that may not be
installed when C<perl Build.PL> is executed, but you've listed in
L</build_requires> so that they should be available when C<./Build> is
executed.

=item build_requires

[version 0.07]

Modules listed in this section are necessary to build and install the
given module, but are not necessary for regular usage of it.  This is
actually an important distinction - it allows for tighter control over
the body of installed modules, and facilitates correct dependency
checking on binary/packaged distributions of the module.

See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
for the details of how requirements can be specified.

=item create_packlist

[version 0.28]

If true, this parameter tells Module::Build to create a F<.packlist>
file during the C<install> action, just like ExtUtils::MakeMaker does.
The file is created in a subdirectory of the C<arch> installation
location.  It is used by some other tools (CPAN, CPANPLUS, etc.) for
determining what files are part of an install.

The default value is true.  This parameter was introduced in
Module::Build version 0.2609; previously no packlists were ever
created by Module::Build.

=item c_source

[version 0.04]

An optional C<c_source> argument specifies a directory which contains
C source files that the rest of the build may depend on.  Any C<.c>
files in the directory will be compiled to object files.  The
directory will be added to the search path during the compilation and
linking phases of any C or XS files.

=item conflicts

[version 0.07]

Modules listed in this section conflict in some serious way with the
given module.  C<Module::Build> (or some higher-level tool) will
refuse to install the given module if the given module/version is also
installed.

See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
for the details of how requirements can be specified.

=item create_makefile_pl

[version 0.19]

This parameter lets you use Module::Build::Compat during the
C<distdir> (or C<dist>) action to automatically create a Makefile.PL
for compatibility with ExtUtils::MakeMaker.  The parameter's value
should be one of the styles named in the L<Module::Build::Compat>
documentation.

=item create_readme

[version 0.22]

This parameter tells Module::Build to automatically create a F<README>
file at the top level of your distribution.  Currently it will simply
use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file
indicated by C<dist_version_from> and put the result in the F<README>
file.  This is by no means the only recommended style for writing a
README, but it seems to be one common one used on the CPAN.

If you generate a F<README> in this way, it's probably a good idea to
create a separate F<INSTALL> file if that information isn't in the
generated F<README>.

=item dist_abstract

[version 0.20]

This should be a short description of the distribution.  This is used
when generating metadata for F<META.yml> and PPD files.  If it is not
given then C<Module::Build> looks in the POD of the module from which
it gets the distribution's version.  It looks for the first line
matching C<$package\s-\s(.+)>, and uses the captured text as the
abstract.

=item dist_author

[version 0.20]

This should be something like "John Doe <[e-mail]>", or if
there are multiple authors, an anonymous array of strings may be
specified.  This is used when generating metadata for F<META.yml> and
PPD files.  If this is not specified, then C<Module::Build> looks at
the module from which it gets the distribution's version.  If it finds
a POD section marked "=head1 AUTHOR", then it uses the contents of
this section.

=item dist_name

[version 0.11]

Specifies the name for this distribution.  Most authors won't need to
set this directly, they can use C<module_name> to set C<dist_name> to
a reasonable default.  However, some agglomerative distributions like
C<libwww-perl> or C<bioperl> have names that don't correspond directly
to a module name, so C<dist_name> can be set independently.

=item dist_version

[version 0.11]

Specifies a version number for the distribution.  See L</module_name>
or L</dist_version_from> for ways to have this set automatically from a
C<$VERSION> variable in a module.  One way or another, a version
number needs to be set.

=item dist_version_from

[version 0.11]

Specifies a file to look for the distribution version in.  Most
authors won't need to set this directly, they can use L</module_name>
to set it to a reasonable default.

The version is extracted from the specified file according to the same
rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>.  It involves finding
the first line that matches the regular expression

   /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/

eval()-ing that line, then checking the value of the C<$VERSION>
variable.  Quite ugly, really, but all the modules on CPAN depend on
this process, so there's no real opportunity to change to something
better.

=item dynamic_config

[version 0.07]

A boolean flag indicating whether the F<Build.PL> file must be
executed, or whether this module can be built, tested and installed
solely from consulting its metadata file.  The main reason to set this
to a true value is that your module performs some dynamic
configuration as part of its build/install process.  If the flag is
omitted, the F<META.yml> spec says that installation tools should
treat it as 1 (true), because this is a safer way to behave.

Currently C<Module::Build> doesn't actually do anything with this flag
- it's up to higher-level tools like C<CPAN.pm> to do something useful
with it.  It can potentially bring lots of security, packaging, and
convenience improvements.

=item extra_compiler_flags

=item extra_linker_flags

[version 0.19]

These parameters can contain array references (or strings, in which
case they will be split into arrays) to pass through to the compiler
and linker phases when compiling/linking C code.  For example, to tell
the compiler that your code is C++, you might do:

  my $build = Module::Build->new
    (
     module_name          => 'Foo::Bar',
     extra_compiler_flags => ['-x', 'c++'],
    );

To link your XS code against glib you might write something like:

  my $build = Module::Build->new
    (
     module_name          => 'Foo::Bar',
     dynamic_config       => 1,
     extra_compiler_flags => scalar `glib-config --cflags`,
     extra_linker_flags   => scalar `glib-config --libs`,
    );

=item get_options

[version 0.26]

You can pass arbitrary command line options to F<Build.PL> or
F<Build>, and they will be stored in the Module::Build object and can
be accessed via the L</args()> method.  However, sometimes you want
more flexibility out of your argument processing than this allows.  In
such cases, use the C<get_options> parameter to pass in a hash
reference of argument specifications, and the list of arguments to
F<Build.PL> or F<Build> will be processed according to those
specifications before they're passed on to C<Module::Build>'s own
argument processing.

The supported option specification hash keys are:


=over 4

=item type

The type of option.  The types are those supported by Getopt::Long; consult
its documentation for a complete list.  Typical types are C<=s> for strings,
C<+> for additive options, and C<!> for negatable options.  If the
type is not specified, it will be considered a boolean, i.e. no
argument is taken and a value of 1 will be assigned when the option is
encountered.

=item store

A reference to a scalar in which to store the value passed to the option.
If not specified, the value will be stored under the option name in the
hash returned by the C<args()> method.

=item default

A default value for the option.  If no default value is specified and no option
is passed, then the option key will not exist in the hash returned by
C<args()>.

=back


You can combine references to your own variables or subroutines with
unreferenced specifications, for which the result will also be stored in the
hash returned by C<args()>.  For example:

  my $loud = 0;
  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     get_options => {
                     loud =>     { store => \$loud },
                     dbd  =>     { type  => '=s'   },
                     quantity => { type  => '+'    },
                    }
    );

  print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
  print "We'll use the ", $build->args('dbd'), " DBI driver\n";
  print "Are you sure you want that many?\n"
    if $build->args('quantity') > 2;

The arguments for such a specification can be called like so:

  perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity

B<WARNING:> Any option specifications that conflict with Module::Build's own
options (defined by its properties) will throw an exception.

Consult the Getopt::Long documentation for details on its usage.

=item include_dirs

[version 0.24]

Specifies any additional directories in which to search for C header
files.  May be given as a string indicating a single directory, or as
a list reference indicating multiple directories.

=item install_path

[version 0.19]

You can set paths for individual installable elements by using the
C<install_path> parameter:

  my $build = Module::Build->new
    (
     ...other stuff here...
     install_path => {
                      lib  => '/foo/lib',
                      arch => '/foo/lib/arch',
                     }
    );

=item installdirs

[version 0.19]

Determines where files are installed within the normal perl hierarchy
as determined by F<Config.pm>.  Valid values are: C<core>, C<site>,
C<vendor>.  The default is C<site>.  See
L<Module::Build/"INSTALL PATHS">

=item license

[version 0.07]

Specifies the licensing terms of your distribution.  Valid options include:


=over 4

=item apache

The distribution is licensed under the Apache Software License
(L<http://opensource.org/licenses/apachepl.php>).

=item artistic