=pod

=begin readme text

Module-Build-Functions version 0.001_005

=end readme

=for readme stop

=head1 NAME

Module::Build::Functions - Module::Install style syntax for Module::Build

=head1 VERSION

This document describes Module::Build::Functions version 0.001_005.

=head1 SYNOPSIS

	# Our own Build.PL.
	use strict;
	$^W = 1; # Can't use "use warnings", see perl_version below.
	use inc::Module::Build::Functions;
	
	module_name         'Module::Build::Functions';
	license             'perl';
	perl_version        '5.005';
	dist_author         'Curtis Jewell <csjewell@cpan.org>';
	dist_version_from   'lib/Module/Build/Functions.pm';
	autosplit           'lib/Module/Build/Functions.pm';
	requires 		    'File::Slurp';
	test_requires       'Test::More';
	test_requires       'Test::Compile';
	add_to_cleanup      'Module-Build-Functions-*';
	create_makefile_pl  'passthrough';
	functions_self_bundler;
	create_build_script;

	# To bundle Module::Build::Functions as above.
	# (Only needs to be ran once if functions_self_bundler is used)
	perl -MModule::Build::Functions -e bundler

=for readme continue
	
=head1 DESCRIPTION

This module gives a Module::Install-like syntax to Module::Build, using 
modules (other than Module::Build itself) that are in the core in 5.006.

Most commands from Module::Install will be supported, and most parameters to
Module::Build's C<new> routine are supported as commands. This includes 
the share directory implementation that L<Module::Install::Share> and 
L<File::ShareDir> implements.

This means that using this module instead of Module::Install can be as easy 
as replacing the C<use inc::Module::Install> line by 
C<use inc::Module::Build::Functions>, and renaming the resulting file to 
Build.PL.

Unfortunately, Module::Install extensions are not supported, nor is the 
L<Module::Install::DSL> syntax.

You may wish to look at the code for documentation at this point, as not 
all functions are documented yet. B<This will be corrected, I promise.>

=begin readme

=head1 INSTALLATION

To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

This method of installation will install a current version of Module::Build 
if it is not already installed.
    
Alternatively, to install with Module::Build, you can use the following commands:

	perl Build.PL
	./Build
	./Build test
	./Build install

=end readme

=for readme stop

=head1 INTERFACE 

All functions are exported by default.

Unless specified otherwise, a function is accumulative - it can be 
called more that once to add to a list.

=head2 Functions unique to Module::Build::Functions

=head3 bundler

	perl -MModule::Build::Functions -e bundler

Writes out a copy of the installed version of Module::Build::Functions in 
the inc directory of your distribution.

=head3 functions_self_bundler

	functions_self_bundler;

Calls the L<bundler> function when Module::Build's C<dist> action (actually 
the C<distmeta> action) is called.

This function is incompatible with the use of C<subclass> in the Build.PL. 
If you need to use subclass for other purposes, add the code below to 
your subclass:

	sub ACTION_distmeta {
		my $self = shift;
		require Module::Build::Functions;
		Module::Build::Functions::bundler();
		$self->SUPER::ACTION_distmeta();
	}


=head2 Module::Build->new parameters (with synonyms noted)

=head3 lists of modules

All lists of modules take a module name (with an optional version) or a 
hashref that contains a list of modules and versions.

Versions are specified as L<Module::Build::Authoring|Module::Build::Authoring#Format_of_prerequisites>
specifies them.

If the version parameter is omitted when one module is being added to the 
list, the version is assumed to be 0.

=head4 build_requires

	build_requires 'Module::CoreList' => 2.17;
	build_requires 'Acme::24';
	build_requires 'Acme' => '!1.11111';

Modules listed using this function are only required for running C<./Build> 
itself, not C<Build.PL>, nor the module(s) being installed.

=head4 conflicts

    conflicts 'Acme' => '1.11111';
	conflicts 'Perl::Dist' => '<1.14';

Modules listed using this function conflict in some serious way with the 
module being installed, and the Build.PL will not continue if these modules 
are already installed.

=head3 Directories

=head4 c_source

	# Not accumulative - only the last c_source is used. 
    c_source 'src';

This function specifies a directory which contains C source files that the 
rest of the build may depend on. 

See L<Module::Build's documentation on c_source()|Module::Build#c_source> 
for more information.

=head4 include_dirs
=head4 include_dir (Module::Build::Functions synonym)

	include_dir 'include';
	include_dir File::Spec->catdir(qw(include xs));
	
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.

=head3 Metadata

Functions in this section are used when generating metadata for I<META.yml> and PPD files. 

=head4 dist_abstract 
=head4 abstract (Module::Install synonym)

	# Not accumulative - only the last dist_abstract or abstract is used. 
	dist_abstract 'Module::Install style syntax for Module::Build';
	abstract 'Module::Install style syntax for Module::Build';

This should be a short description of the distribution. 
	
If either this function, L<#abstract_from>, or L<#all_from> is not given, 
then Module::Build looks in the POD of the module from which it gets the 
distribution's version. If it finds a POD section marked "=head1 NAME", then 
it looks for the first line matching \s+-\s+(.+), and uses the captured text 
as the abstract.

=head4 dist_author
=head4 author (Module::Install synonym)

	dist_author 'John Doe <jdoe@example.com>';
	author 'Jane Doe <doej@example.com>';
	
This should be something like "John Doe <jdoe@example.com>", or if there are 
multiple authors, this routine can be called multiple times, or an anonymous 
array of strings may be specified. 
	
If either this function, L<author_from>, or L<#all_from> is not used, then 
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.

=head4 dist_name

	dist_name 'Module-Build-Functions';

Specifies the name for this distribution. Most authors won't need to set this directly, they can use L<#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.

=head4 dist_version
=head4 version (Module::Install synonym)

	dist_version '0.001_001';

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.

=head4 dist_version_from
=head4 version_from (Module::Install synonym)

	dist_version_from 'lib/Module/Build/Functions.pm';

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


=head3 Flags

Functions listed here are B<not> accumulative - only the last value a flag has 
been set to will apply.

=head4 create_packlist

	create_packlist 1;
	
If this flag is set (and it is set by default), Module::Build will create a .packlist 
file duting the L<install> action.

=head4 create_makefile_pl

    create_makefile_pl 'small';
    create_makefile_pl 'passthrough';
    create_makefile_pl 'traditional';

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

=head4 create_readme

    create_readme 1;

This function tells Module::Build whether to automatically create a README 
file at the top level of your distribution or not. Currently it will simply 
use Pod::Text (or Pod::Readme if it's installed) on the file indicated by 
dist_version_from and put the result in the 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 README in this way, it's probably a good idea to create a 
separate INSTALL file if that information isn't in the generated README.

=head4 create_license

    create_license 1;

This function tells Module::Build whether to automatically create a LICENSE 
file at the top level of your distribution or not. If set to 1, it creates 
a LICENSE file based on the license you give for your META.yml file.

This requires L<Software::License> to be installed.

=head4 dynamic_config

	dynamic_config 1;

This function indicates whether the 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 META.yml spec says that 
installation tools should treat it as 1 (true), because this is a safer way 
to behave.

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

=head4 installdirs

	# Not accumulative - last one of installdirs or 
	# any aliases to installdirs will be used.
	installdirs 'site';
	installdirs 'core';
	installdirs 'vendor';
	
Determines where files are installed within the normal perl hierarchy as 
determined by Config.pm. Valid values are: core, site, vendor. The 
default is site. See L<Module::Build#INSTALL PATHS>

=head4 license

	license 'perl';

Specifies the licensing terms of your distribution. Valid licenses are listed in 
L<Module::Build::API>.

=head3 Other functions

=head4 add_to_cleanup
 
	add_to_cleanup 'Module-Build-Functions-*';
	add_to_cleanup 'Makefile';
	 
Adds a file specification (or an arrayref of file specifications) to the 
list of files to cleanup when the C<clean> action is performed.

=head4 auto_features

    auto_features 'pg_support',    'description' => 'Interface with Postgres databases';
    auto_features 'pg_support',    'requires'    => 'DBD::Pg'                 => '23.3';
    auto_features 'pg_support',    'requires'    => 'DateTime::Format::Pg'    => 0;
    auto_features 'mysql_support', 'description' => 'Interface with MySQL databases';
    auto_features 'mysql_support', 'requires'    => 'DBD::mysql'              => '17.9';
    auto_features 'mysql_support', 'requires'    => 'DateTime::Format::MySQL' => 0;

This parameter supports the setting of features (see L<"Module::Build|feature($name)">) 
automatically based on a set of prerequisites.

*WARNING* The syntax for this may change before 1.000!
	
=head4 autosplit

	autosplit           'lib/Module/Build/Functions.pm';
	
Adds a file (or an arrayref containing a list of files) that need(s) to 
have L<Autosplit::autosplit()|Autosplit#autosplit> ran on them
(because the file in question uses L<AutoLoader>, most likely).

=head4 build_class

	# Not accumulative - only the last build_class is used. 
	build_class 'Module::Build::Subclass';

Sets the name of a subclass of Module::Build that the Build script uses.

This is used if the subclass has requirements that are satisfied by 
L<#build_requires>, but are not neccessarily installed when Build.PL 
will be executed.

=head4 extra_compiler_flags
=head4 extra_linker_flags

These parameters can contain strings (which are split on whitespace and accumulate into an array reference in the order added) or array references 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:

    extra_compiler_flags '-x c++';

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

    extra_compiler_flags scalar `glib-config --cflags`;
    extra_linker_flags   scalar `glib-config --libs`;

=head3 Supported Module::Install syntax
	
=head4 install_as_core
=head4 install_as_cpan

Alias for C<installdirs 'core';>. See L<#installdirs>.

=head4 install_as_site

Alias for C<installdirs 'site';>. See L<#installdirs>.

=head4 install_as_vendor

Alias for C<installdirs 'vendor';>. See L<#installdirs>.

	 
=head1 DIAGNOSTICS

=for author to fill in:
    List every single error and warning message that the module can
    generate (even the ones that will "never happen"), with a full
    explanation of each problem, one or more likely causes, and any
    suggested remedies.

=over

=item C<< %s cannot be found >>

There was probably a misspelling in the command name in the Build.PL.

=item C<< %s is not supported yet >>

Module::Build::Functions is not completely implemented yet, so a number of
functions will croak with this error.

Hang on, support will be coming soon!

=item C<< auto_install is deprecated >>

The author has deliberately chosen to drop support for auto_install.
(he happens to be irritated at pre-0.86 Module::Installs that stop 
CPAN upgrades to make him answer an unneeded question.)

Patches, however, would be welcomed to implement an auto_install that 
is not annoying.

=item C<< Invalid install type >>
=item C<< Illegal or invalid share dir type '%s' >>
=item C<< Illegal or missing directory install_share param >>
=item C<< Missing or invalid module name '%s' >>
=item C<< Too many parameters to install_share  >>
=item C<< cannot add directory %s to a list of script_files >>
=item C<< attempt to overwrite string script_files with %s failed  >>
=item C<< cannot add a glob to a list of test_files  >>
=item C<< attempt to overwrite string test_files failed  >>

Will be documented soon.

=back

=head1 CONFIGURATION AND ENVIRONMENT
  
Module::Build::Functions requires no configuration files or environment 
variables of its own. See L<Module::Build> for its configuration variables
or environment variables.

=for readme continue

=head1 DEPENDENCIES

File::Slurp and Module::Build are required on the system of an author 
using this module in his Build.PL.

On the system of the person installing a module using 
Module::Build::Functions, only Module::Build is required.  The version of 
Module::Build that will be required is determined by the functions used.

=for readme stop

=head1 INCOMPATIBILITIES

=for author to fill in:
    A list of any modules that this module cannot be used in conjunction
    with. This may be due to name conflicts in the interface, or
    competition for system or program resources, or due to internal
    limitations of Perl (for example, many modules that use source code
    filters are mutually incompatible).

None reported.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to the author at the e-mail
address below for the moment.

=for author to correct:
	Please report any bugs or feature requests to
	C<bug-Module-Build-Functions@rt.cpan.org>, or through the web interface at
	L<http://rt.cpan.org>.

=head1 AUTHOR

Curtis Jewell  C<< <csjewell@cpan.org> >>

=for readme continue

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2009, Curtis Jewell C<< <csjewell@cpan.org> >>. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

=for readme stop

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.