view release on metacpan or  search on metacpan

inc/inc_Module-Build/Module/Build/API.pod  view on Meta::CPAN

[version 0.36]

An optional parameter specifying directories of static data files to
be installed as read-only files for use with L<File::ShareDir>.  The
C<share_dir> property supports both distribution-level and
module-level share files.

The simplest use of C<share_dir> is to set it to a directory name or an
arrayref of directory names containing files to be installed in the
distribution-level share directory.

  share_dir => 'share'

Alternatively, if C<share_dir> is a hashref, it may have C<dist> or
C<module> keys providing full flexibility in defining how share
directories should be installed.

  share_dir => {
    dist => [ 'examples', 'more_examples' ],
    module => {
      Foo::Templates => ['share/html', 'share/text'],
      Foo::Config    => 'share/config',
    }
  }

If C<share_dir> is set, then File::ShareDir will automatically be added
to the C<requires> hash.

=item sign

[version 0.16]

If a true value is specified for this parameter, L<Module::Signature>
will be used (via the 'distsign' action) to create a SIGNATURE file
for your distribution during the 'distdir' action, and to add the
SIGNATURE file to the MANIFEST (therefore, don't add it yourself).

The default value is false.  In the future, the default may change to
true if you have C<Module::Signature> installed on your system.

=item tap_harness_args

[version 0.2808_03]

An optional parameter specifying parameters to be passed to TAP::Harness when
running tests. Must be given as a hash reference of parameters; see the
L<TAP::Harness|TAP::Harness> documentation for details. Note that specifying
this parameter will implicitly set C<use_tap_harness> to a true value. You
must therefore be sure to add TAP::Harness as a requirement for your module in
L</build_requires>.

=item test_files

[version 0.23]

An optional parameter specifying a set of files that should be used as
C<Test::Harness>-style regression tests to be run during the C<test>
action.  May be given as an array reference of the files, or as a hash
reference whose keys are the files (and whose values will currently be
ignored).  If the argument is given as a single string (not in an
array reference), that string will be treated as a C<glob()> pattern
specifying the files to use.

The default is to look for a F<test.pl> script in the top-level
directory of the distribution, and any files matching the glob pattern
C<*.t> in the F<t/> subdirectory.  If the C<recursive_test_files>
property is true, then the C<t/> directory will be scanned recursively
for C<*.t> files.

=item use_tap_harness

[version 0.2808_03]

An optional parameter indicating whether or not to use TAP::Harness for
testing rather than Test::Harness. Defaults to false. If set to true, you must
therefore be sure to add TAP::Harness as a requirement for your module in
L</build_requires>. Implicitly set to a true value if C<tap_harness_args> is
specified.

=item xs_files

[version 0.19]

Just like C<pm_files>, but used for specifying the set of C<.xs>
files in your distribution.

=back


=item new_from_context(%args)

[version 0.28]

When called from a directory containing a F<Build.PL> script (in other words,
the base directory of a distribution), this method will run the F<Build.PL> and
call C<resume()> to return the resulting C<Module::Build> object to the caller.
Any key-value arguments given to C<new_from_context()> are essentially like
command line arguments given to the F<Build.PL> script, so for example you
could pass C<< verbose => 1 >> to this method to turn on verbosity.

=item resume()

[version 0.03]

You'll probably never call this method directly, it's only called from the
auto-generated C<Build> script (and the C<new_from_context> method).  The
C<new()> method is only called once, when the user runs C<perl Build.PL>.
Thereafter, when the user runs C<Build test> or another action, the
C<Module::Build> object is created using the C<resume()> method to
re-instantiate with the settings given earlier to C<new()>.

=item subclass()

[version 0.06]

This creates a new C<Module::Build> subclass on the fly, as described
in the L<Module::Build::Authoring/"SUBCLASSING"> section.  The caller
must provide either a C<class> or C<code> parameter, or both.  The
C<class> parameter indicates the name to use for the new subclass, and
defaults to C<MyModuleBuilder>.  The C<code> parameter specifies Perl
code to use as the body of the subclass.

=item add_property

[version 0.31]

inc/inc_Module-Build/Module/Build/API.pod  view on Meta::CPAN

When this method is called, a new property will be installed in the
Module::Build class, and an accessor will be built to allow the property to be
get or set on the build object.

  print $build->pedantic, $/;
  $build->pedantic(0);

If the default value is a hash reference, this generates a special-case
accessor method, wherein individual key/value pairs may be set or fetched:

  print "stuff{foo} is: ", $build->stuff( 'foo' ), $/;
  $build->stuff( foo => 'bar' );
  print $build->stuff( 'foo' ), $/; # Outputs "bar"

Of course, you can still set the entire hash reference at once, as well:

  $build->stuff( { foo => 'bar', baz => 'yo' } );

In either case, if a C<check> has been specified for the property, it will be
applied to the entire hash. So the check code reference should look something
like:

      check => sub {
            return 1 if defined $_ && exists $_->{foo};
            shift->property_error(qq{Property "stuff" needs "foo"});
            return 0;
      },

=item property_error

[version 0.31]

=back


=head2 METHODS

=over 4

=item add_build_element($type)

[version 0.26]

Adds a new type of entry to the build process.  Accepts a single
string specifying its type-name.  There must also be a method defined
to process things of that type, e.g. if you add a build element called
C<'foo'>, then you must also define a method called
C<process_foo_files()>.

See also
L<Module::Build::Cookbook/"Adding new file types to the build process">.

=item add_to_cleanup(@files)

[version 0.03]

You may call C<< $self->add_to_cleanup(@patterns) >> to tell
C<Module::Build> that certain files should be removed when the user
performs the C<Build clean> action.  The arguments to the method are
patterns suitable for passing to Perl's C<glob()> function, specified
in either Unix format or the current machine's native format.  It's
usually convenient to use Unix format when you hard-code the filenames
(e.g. in F<Build.PL>) and the native format when the names are
programmatically generated (e.g. in a testing script).

I decided to provide a dynamic method of the C<$build> object, rather
than just use a static list of files named in the F<Build.PL>, because
these static lists can get difficult to manage.  I usually prefer to
keep the responsibility for registering temporary files close to the
code that creates them.

=item args()

[version 0.26]

  my $args_href = $build->args;
  my %args = $build->args;
  my $arg_value = $build->args($key);
  $build->args($key, $value);

This method is the preferred interface for retrieving the arguments passed via
command line options to F<Build.PL> or F<Build>, minus the Module-Build
specific options.

When called in in a scalar context with no arguments, this method returns a
reference to the hash storing all of the arguments; in an array context, it
returns the hash itself.  When passed a single argument, it returns the value
stored in the args hash for that option key.  When called with two arguments,
the second argument is assigned to the args hash under the key passed as the
first argument.

=item autosplit_file($from, $to)

[version 0.28]

Invokes the L<AutoSplit> module on the C<$from> file, sending the
output to the C<lib/auto> directory inside C<$to>.  C<$to> is
typically the C<blib/> directory.

=item base_dir()

[version 0.14]

Returns a string containing the root-level directory of this build,
i.e. where the C<Build.PL> script and the C<lib> directory can be
found.  This is usually the same as the current working directory,
because the C<Build> script will C<chdir()> into this directory as
soon as it begins execution.

=item build_requires()

[version 0.21]

Returns a hash reference indicating the C<build_requires>
prerequisites that were passed to the C<new()> method.

=item can_action( $action )

Returns a reference to the method that defines C<$action>, or false
otherwise. This is handy for actions defined (or maybe not!) in subclasses.