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

VERSION
    This document describes Module::Build::Functions version 0.001_010.

SYNOPSIS
            # Our own Build.PL.
            # $^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';
            test_requires       'Capture::Tiny' => 0.06;
            add_to_cleanup      'Module-Build-Functions-*';
            create_makefile_pl  'passthrough';
            
        create_build_script;

    or in more relaxed DSL notation:

        use inc::Module::Build::Functions::DSL;
        
    module_name         MBF::Test
        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
        test_requires       Capture::Tiny   0.06
        add_to_cleanup      Module-Build-Functions-*
        create_makefile_pl  passthrough

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 are 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. Module::Install::DSL syntax is also supported with
    Module::Build::Functions::DSL.

    Unfortunately, Module::Install extensions are not supported.

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
   cygwin
            some_code if cygwin;

    Returns true if $^O equals cygwin.

   get_builder
            my $mb_object = get_builder();

    Creates the Module::Build object (or returns it if already created)
    defined by the functions previously executed in this module.

  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.

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

    Modules listed using this function are required for using the module(s)
    being installed.

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

    Modules listed using this function are recommended, but not required,
    for using the module(s) being installed.

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

    Modules listed using this function are required for running the
    distribution's "Build.PL".

    Note: Module::Build does not need to be added to this list, as
    Module::Build::Functions will determine the version of Module::Build
    required for the functions used.

   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.

    Note: Module::Build does not need to be added to this list, as
    Module::Build::Functions will determine the version of Module::Build
    required for the functions used.

   test_requires
        test_requires       'Test::More';
        test_requires       'Test::Compile' => 0.01;
        test_requires       'Capture::Tiny' => 0.06;

    Modules listed using this function are required for running the
    distribution's test suite.

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

   install_path
            install_path 'lib' '/foo/lib';
            install_path 'man' File::Spec->catdir(File::Spec->rootdir(), 'foo', 'man');

    To set specific locations for different types of installable elements,
    call "install_path" with the type of installable element and the
    location where it should be installed.

    *Recommendation*: Don't use this unless you are either deliberately
    installing outside the default perl library directories, or installing a
    new type, defined by "install_path".

   Files
   PL_files
   pl_files
   Pl_file
   pl_file
    An optional parameter specifying a set of ".PL" files in your
    distribution. These will be run as Perl scripts prior to processing the
    rest of the files in your distribution with the name of the file they're
    generating as an argument. They are usually used as templates for
    creating other files dynamically, so that a file like
    "lib/Foo/Bar.pm.PL" might create the file "lib/Foo/Bar.pm".

    The files are specified with the ".PL" files as hash keys, and the
    file(s) they generate as hash values, like so:

      my $build = Module::Build->new
        (
         module_name => 'Foo::Bar',
         ...
         PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
        );

    Note that the path specifications are *always* given in Unix-like
    format, not in the style of the local system.

    If your ".PL" scripts don't create any files, or if they create files
    with unexpected names, or even if they create multiple files, you can
    indicate that so that Module::Build can properly handle these created
    files:

      PL_files => {
                   'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
                   'lib/something.PL'  => ['/lib/something', '/lib/else'],
                   'lib/funny.PL'      => [],
                  }

    Here's an example of a simple PL file.

        my $output_file = shift;
        open my $fh, ">", $output_file or die "Can't open $output_file: $!";

        print $fh <<'END';
        #!/usr/bin/perl

        print "Hello, world!\n";
        END

    PL files are not installed by default, so its safe to put them in lib/
    and bin/.

   pm_files
    An optional parameter specifying the set of ".pm" files in this
    distribution, specified as a hash reference whose keys are the files'
    locations in the distributions, and whose values are their logical
    locations based on their package name, i.e. where they would be found in
    a "normal" Module::Build-style distribution. This parameter is mainly
    intended to support alternative layouts of files.

    For instance, if you have an old-style "MakeMaker" distribution for a
    module called "Foo::Bar" and a Bar.pm file at the top level of the
    distribution, you could specify your layout in your "Build.PL" like
    this:

      my $build = Module::Build->new
        (
         module_name => 'Foo::Bar',
         ...
         pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
        );

    Note that the values should include "lib/", because this is where they
    would be found in a "normal" Module::Build-style distribution.

    Note also that the path specifications are *always* given in Unix-like
    format, not in the style of the local system.

   pod_files
   pod_file
    Just like "pm_files", but used for specifying the set of ".pod" files in
    your distribution.

   xs_file
   xs_files
    Just like "pm_files", but used for specifying the set of ".xs" files in
    your distribution.

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

   all_from
            all_from 'lib\Module\Build\Functions.pm';

    Specifies the file to look for the abstract, the author, the version,
    the license, and the perl version required in.

   dist_abstract
   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.

   abstract_from
            abstract_from 'lib\Module\Build\Functions.pm';

    Specifies a file to look for the abstract in.

   dist_author
   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.

   author_from (Module::Install synonym)
            author_from 'lib\Module\Build\Functions.pm';

    Specifies a file to look for the author in, using the contents of a POD
    section marked "=head1 AUTHOR" or "=head1 AUTHORS".

    If either this function, "author", "dist_author",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.

   name (Module::Install synonym)
   module_name
            module_name 'Module::Build::Functions';

    Specifies the name of the main module for this distribution. This will
    set the distribution's name and version.

   dist_version
   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.

   perl_version
            perl_version '5.006001';

    Specifies a minimum version of perl that this distribution requires.

   perl_version_from
            perl_version_from 'lib\Module\Build\Functions.pm';

    Specifies a file to look for the minimum perl version in.

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

   license
            license 'perl';

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

   license_from
            license_from 'lib\Module\Build\Functions.pm';

    Specifies a file to look for the choice of license in.

   meta_add
   meta_merge
            meta_add 'provides' { 'Module::Build::Functions' => { file => 'lib\Module\Build\Functions.pm', version => '0.001_010'} };
            meta_merge 'resources' 'bugtracker' 'http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Build-Functions';

    meta_add and meta_merge adds their parameters to the "META.yml" file.

    The first parameter is the key to add or merge to, and the second
    parameter is the value of that key (which may be a string, an arrayref,
    or a hashref.)

    The one difference is that meta_add overwrites anything else in that
    key, while meta_merge will merge an arrayref or hashref into the current
    contents of the key.

    Also, meta_merge allows a hashref to be ommitted if it contains only one
    value.

   no_index
      no_index directory => 'examples';
      no_index package   => 'DB';

    Quite often a distrubition will provide example scripts or testing
    modules (.pm files) as well as the actual library modules.

    In almost all situations, you do not want these indexed in the CPAN
    index, the master Perl packages list, or displayed on the
    <http://search.cpan.org/> website, you just want them along for the
    ride.

    The "no_index" command is used to indicate directories or files where
    there might be non-library .pm files or other files that the CPAN
    indexer and websites such as <http://search.cpan.org/> should explicitly
    ignore.

    The most common situation is to ignore example or demo directories, but
    a variety of different situations may require a "no_index" entry.

    Another common use for "no_index" is to prevent the PAUSE indexer
    complaining when your module makes changes inside a "package DB" block.
    This is used to interact with the debugger in some specific ways.

    See the META.yml documentation for more details on what "no_index"
    values are allowed.

    The inc, t and share (if "install_share" is used) directories are
    automatically "no_index"'ed for you if found and do not require an
    explicit command.

    To summarize, if you can see it on <http://search.cpan.org/> and you
    shouldn't be able to, you need a "no_index" entry to remove it.

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

   create_packlist
            create_packlist 1;
            create_packlist 0; # Not recommended.

    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;
            dynamic_config 0;

    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"

   recursive_test_files
            recursive_test_files 1;

    If this is set to 1, Module::Build will search recursively under "/t"
    for "*.t" files to use when testing. Defaults to 0.

   sign
            sign 1;

    If this is set to 1, Module::Build will use Module::Signature to create
    a signature file for your distribution during the "distdir" action.

   use_tap_harness
            use_tap_harness 1;
            use_tap_harness 0;

    This indicates whether or not to use TAP::Harness for testing rather
    than Test::Harness. Defaults to false. If set to true, you must add
    TAP::Harness as a requirement for your module in "build_requires".

    This will be set to a true value if tap_harness_args is specified.

   tap_harness_args
            use_tap_harness { verbosity => 1, lib => [ 'lib', 'blib/lib', 'blib/arch' ] };

    This indicates the options to use when TAP::Harness is used for testing,
    and is given as a hash reference.

    If set, you must add TAP::Harness as a requirement for your module in
    "build_requires".

    WARNING: May change to a accumulative function in future versions.

   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_configure_requires
        auto_configure_requires 0;
        auto_configure_requires 1;

    This parameter determines whether Module::Build will be added to
    'configure_requires' (and 'build_requires') if Module::Build is not
    already there. The required version will be the last 'major' release, as
    defined by the decimal version truncated to two decimal places (e.g.
    0.34, instead of 0.3402). The default value is true.

   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.

    If the subclass, specified with this directive, define some additional
    propeties, helper functions for them will be exported in the building
    script automatically. However, if this will happened at run-time, they
    should be used with parenthesis:

        use inc::Module::Build::Functions;
        
    build_class 'Module::Build::SubClass';
        
    custom_flag('flag_set');
        
    custom_array(1);
        custom_array(10);
        
    custom_hash(key1 => 'value1');
        custom_hash(key2 => 'value2');
        
    module_name         'MBF::Test';
        dist_version_from   'lib/MBF/Test.pm';
        
    create_build_script;

    To use new helper functions without parenthesis, specify the
    'build_class' in the parameters for 'import' method:

        use inc::Module::Build::Functions( build_class => 'Module::Build::SubClass' );
        
    custom_flag 'flag_set';
        
    custom_array    1;
        custom_array    10;
        
    custom_hash     key1 => 'value1';
        custom_hash     key2 => 'value2';
        
    module_name         'MBF::Test';
        dist_version_from   'lib/MBF/Test.pm';
        
    create_build_script;

    See also "additional_hash", "additional_array", "additional_flag".

   extra_compiler_flags
   extra_linker_flags
    *Aliases*: "extra_compiler_flag", "extra_linker_flag"

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

   get_options
            get_options loud => { store => \$loud };
            get_options dbd => { type => '=s' };
            get_options quantity => { type => '+' };

    Adds a command line parameter (or a hashref of command line parameters)
    that the "Build.PL" or "Build" script is to process according to the
    specifications given (the specification hashrefs are documented in the
    Module::Build::API documentation.)

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

   create_build_script
   WriteAll (Module::Install synonym)
    Creates the *Build.PL* to be run in future steps, and returns the
    Module::Build object created.

   Supported Module::Install syntax not mentioned above
   install_as_core
   install_as_cpan
    Aliases for "installdirs 'core';". See installdirs.

   install_as_site
    Alias for "installdirs 'site';". See installdirs.

   install_as_vendor
    Alias for "installdirs 'vendor';". See installdirs.

   win32
            requires 'Win32' 0.30 if win32;

    Returns true if $^O eq 'MSWin32'.

   winlike
            requires 'Win32' 0.28 if winlike;

    Returns true if $^O eq 'cygwin' or $^O eq 'MSWin32'.

   release_testing
   automated_testing
    Returns true if the appropriate environment variable is set to something
    that is true.

   requires_external_bin
            configure_requires 'ExtUtils::MakeMaker' 6.52 if cygwin;
            requires_external_bin 'svn';

    This routine checks that a particular command is available on the host
    system.

    The *Build.PL* file will abort with an *NA* result if the command is not
    available.

    The example code shows the one limitation on this routine - because of a
    bug in ExtUtils::MakeMaker, this routine does not find some commands on
    Cygwin systems until pre-release versions of ExtUtils::MakeMaker 6.52.

   requires_external_cc
            requires_external_cc;

    This routine checks that there is a compiler and linker on the system,
    and that they actually work, by calling
    ExtUtils::CBuilder::have_compiler.

    The *Build.PL* file will abort with an *NA* result if the command is not
    available.

   can_run
            configure_requires 'ExtUtils::MakeMaker' 6.52 if cygwin;
            my $has_svn = can_run 'svn';

    This routine returns whether a particular command is available on the
    system.

    The example code shows the one limitation on this routine - because of a
    bug in ExtUtils::MakeMaker, this routine does not find some commands on
    Cygwin systems until pre-release versions of ExtUtils::MakeMaker 6.52.

   can_cc
            my $has_compiler = can_cc;

    This routine returns whether there is a compiler and linker on the
    system, and that they actually work, by calling
    ExtUtils::CBuilder::have_compiler to verify that fact.

   can_use
            my $has_perl_svn = can_use 'SVN::Core';
            my $has_real_alien_wix = can_use 'Alien::WiX', 0.300001;

    The can_use function tests the ability to load a specific named module.
    Currently it will load the module in the process, although this may
    change in the future.

    Takes an optional second param of a version number. The currently
    installed version of the module will be tested to make sure it is equal
    to or greater than the specified version.

   author_context;
            my $is_author = author_context;
            if (author_context) { ... }

    Returns true if being run by the author.

    This is determined by looking for the "inc/.author" directory, trying to
    detect a version control system, and looking for the *MANIFEST.SKIP*
    file, in that order.

   repository
            repository 'http://svn.ali.as/cpan/trunk/Module-Build-Functions/';

    Alias for "meta_merge 'resources', 'repository' => $url".
    <http://search.cpan.org/> will use this to display the repository on the
    distribution's main page.

   bugtracker
            bugtracker 'http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Build-Functions';

    Alias for "meta_merge 'resources', 'bugtracker' => $url".
    <http://search.cpan.org/> will use this instead of its usual link to
    rt.cpan.org to report bugs from the repository's main page.

   script_files
   script_file
   install_script (Module::Install synonym)
            # The following are equivalent
            install_script 'foo';
            install_script 'script/foo';

    XXX

    The 'script_files' command provides support for the installation of
    scripts that will become available at the console on both Unix and
    Windows (in the later case by wrapping it up as a .bat file). To support
    less typing, if a script is located in the "/script" directory, you need
    refer to it by name only.

    XXX

    An optional parameter specifying a set of files that should be installed
    as executable Perl scripts when the module is installed. May be given as
    an array reference of the files, as a hash reference whose keys are the
    files (and whose values will currently be ignored), as a string giving
    the name of a directory in which to find scripts, or as a string giving
    the name of a single script file.

    The default is to install any scripts found in a 'bin' directory at the
    top level of the distribution, minus any keys of PL_files.

   interactive
            print "A question I need a user to see.\n" if interactive;

    Returns true if in an interactive environment, or false otherwise.

   install_share
            # These are the same - they put files in the 'share' directory
        # where File::ShareDir::dist_dir or dist_file can access them 
            # when your module is used.     
            install_share;
            install_share 'dist', 'share';

            # If you want to call the directory within your distribution
            # something different, you can.
            install_share 'dist', 'data';
            
        # This installs a share directory for a module, where
        # File::ShareDir::module_dir or module_file can find the files 
            # when your module is used.
            install_share 'module' => 'Perl::Dist::WiX', File::Spec->catdir('data', 'WiX');
            install_share 'module' => 'Perl::Dist::Inno', File::Spec->catdir('data', 'Inno');
            install_share 'module' => 'Acme::Angels', 'data';

    This command provides a way for modules or distributions to install
    read-only data in a way that is easily findable after installation, and
    is not operating system dependent.

    The first parameter is either 'dist' or 'module', and specifies the type
    of directory this is - whether it applies to the whole distribution, or
    only a single module (and it's subclasses, see
    File::ShareDir::class_file()). If installing files for a module, the
    module name is required, as well. This defaults to 'dist' if not given.

    The last parameter is the directory in your distribution that contains
    the files to install, and defaults to 'share' for a distribution,
    although if a type is given, a directory must be, as well. The directory
    is given in local file system format, so you may wish to use File::Spec
    to stitch two or more directories together, as shown above.

    Unlike Module::Install's "install_share", this will NOT install a file
    that is not in the *MANIFEST*, so you may need to alter your *MANIFEST*
    or *MANIFEST.SKIP* files to let certain files through if they would
    ordinarily be skipped. If the "MANIFEST" file cannot be read, then no
    files are copied, and the "Build.PL" script stops. You have been warned.

   Additional properties definition
    This group of directives is mostly required for non-trivial subclassing
    of Module::Build. Module::Build::Functions do its best to find new
    properties from subclasses transparently.

    Every directive in this group accepts a single argument - the name of
    new property. The helper function with corresponding name will be
    exported to the script's scope. See also "build_class" for additional
    details.

   additional_hash
    This directive define a new "hash" property. Property will be
    accumulative:

        use inc::Module::Build::Functions;
        
    additional_hash 'custom_hash';
        
    custom_hash(key1 => 'value1');
        custom_hash(key2 => 'value2');
        ...

   additional_array
    This directive define a new "array" property. Property will be
    accumulative:

        use inc::Module::Build::Functions;
        
    additional_hash 'custom_array';
        
    custom_array('value1');
        custom_array('value2');
        ...

   additional_flag
    This directive define a new "flag" (non-accumulative) property.

        use inc::Module::Build::Functions;
        
    additional_flag 'custom_custom';
        
    custom_flag('value');
        ...

   Deprecated directives
   auto_bundle
   auto_bundle_deps
   bundle
   bundle_deps
    This directives comes from Module::Install::Bundle. The author has
    deliberately chosen to drop support for bundling at this point, since
    Module::Build quite probably will have native bundling capabilities
    soon.

   auto_install
    This directive comes from Module::Install::AutoInstall and is
    deprecated, as its support in the Module::Install::AutoInstall itself
    may be dropped soon.

   check_nmake
    This directive is deprecated in the Module::Install itself.

   get_file
   Directives to be documented
   test_file
   test_files
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. Of COURSE, I
        want prerequisites installed. Why would I not?)

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

    "bundle is deprecated"
    "auto_bundle is deprecated"
    "bundle_deps is deprecated"
    "auto_bundle_deps is deprecated"
        The author has deliberately chosen to drop support for bundling at
        this point.

        Patches, however, would be welcomed.

    "Invalid install type"
    "Illegal or invalid share dir type '%s'"
    "Illegal or missing directory install_share param"
    "Missing or invalid module name '%s'"
    "Too many parameters to install_share"
    "cannot add directory %s to a list of script_files"
    "attempt to overwrite string script_files with %s failed"
    "cannot add a glob to a list of test_files"
    "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.

    Capture::Tiny version 0.06 or greater is used during testing only.

    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
    "bug-Module-Build-Functions@rt.cpan.org", or through the web interface
    at <http://rt.cpan.org>.

AUTHOR
    Curtis Jewell "<csjewell@cpan.org>"

LICENSE 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, either version 5.005_04 or any
    later version. See perlartistic and perlgpl.

    The full text of the license can be found in the LICENSE file included
    with this module.

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.

