/ 
Module-Build-Functions-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Module::Build::Functions

NAME

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

VERSION

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

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

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 new routine are supported as commands. This includes the share directory implementation that Module::Install::Share and File::ShareDir implements.

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

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

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

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.

Functions unique to Module::Build::Functions

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.

functions_self_bundler

functions_self_bundler;

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

This function is incompatible with the use of 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();
}

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

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 Module::Build::Authoring specifies them.

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

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 ./Build itself, not Build.PL, nor the module(s) being installed.

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.

Directories

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 Module::Build's documentation on c_source() for more information.

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.

Metadata

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

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, #abstract_from, or #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.

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, author_from, or #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.

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 #module_name to set dist_name to a reasonable default. However, some agglomerative distributions like libwww-perl or bioperl have names that don't correspond directly to a module name, so dist_name can be set independently.

dist_version =head4 version (Module::Install synonym)

dist_version '0.001_001';

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

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 module_name to set it to a reasonable default.

Flags

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

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 install action.

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 distdir (or 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 Module::Build::Compat documentation.

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.

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 Software::License to be installed.

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.

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 "Module::Build#INSTALL PATHS"

license

license 'perl';

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

Other functions

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 clean action is performed.

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 "Module::Build) automatically based on a set of prerequisites.

*WARNING* The syntax for this may change before 1.000!

autosplit

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

Adds a file (or an arrayref containing a list of files) that need(s) to have Autosplit::autosplit() ran on them (because the file in question uses AutoLoader, most likely).

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 #build_requires, but are not neccessarily installed when Build.PL will be executed.

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`;

Supported Module::Install syntax

install_as_core =head4 install_as_cpan

Alias for installdirs 'core';. See #installdirs.

install_as_site

Alias for installdirs 'site';. See #installdirs.

install_as_vendor

Alias for installdirs 'vendor';. See #installdirs.

DIAGNOSTICS

%s cannot be found

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

%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!

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.

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

Will be documented soon.

CONFIGURATION AND ENVIRONMENT

Module::Build::Functions requires no configuration files or environment variables of its own. See Module::Build for its configuration variables or environment variables.

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.

INCOMPATIBILITIES

None reported.

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.

AUTHOR

Curtis Jewell <csjewell@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2009, Curtis Jewell <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 perlartistic.

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.