NAME
    Module::Build::Bundle - subclass for supporting Tasks and Bundles

VERSION
    This documentation describes version 0.14

SYNOPSIS
        #In your Build.PL
        use Module::Build::Bundle;

        #Example lifted from: Perl::Critic::logicLAB
        my $build = Module::Build::Bundle->new(
            dist_author   => 'Jonas B. Nielsen (jonasbn), <jonasbn@cpan.org>',
            module_name   => 'Perl::Critic::logicLAB',
            license       => 'artistic',
            create_readme => 1,
            requires      => {
                'Perl::Critic::Policy::logicLAB::ProhibitUseLib' => '0',
                'Perl::Critic::Policy::logicLAB::RequireVersionFormat' => '0',
            },
        );

        $build->create_build_script();


        #In your shell
        % ./Build contents

        #Or implicitly executing contents action
        % ./Build

DESCRIPTION
  FEATURES
    *   Autogeneration of POD for Bundle and Task distributions via a build
        action

    *   Links to required/listed distributions, with or without versions

    *   Links to specific versions of distributions for perl 5.12.0 or newer
        if a version is specified

    *   Inserts a POD section named CONTENTS or something specified by the
        caller

    This module adds a very basic action for propagating a requirements list
    from a Build.PL file's requires section to the a POD section in a
    designated distribution.

SUBROUTINES/METHODS
  ACTION_contents
    This is the build action parsing the requirements specified in the
    Build.PL file. It creates a POD section (see also "FEATURES" above).

    By default it overwrites the CONTENTS section with a POD link listing.
    You can specify a note indicating if what section you want to overwrite
    using the section_header note.

        #Example lifted from: Perl::Critic::logicLAB
        my $build = Module::Build::Bundle->new(
            dist_author   => 'Jonas B. Nielsen (jonasbn), <jonasbn@cpan.org>',
            module_name   => 'Perl::Critic::logicLAB',
            license       => 'artistic',
            create_readme => 1,
            requires      => {
                'Perl::Critic::Policy::logicLAB::ProhibitUseLib' => '0',
                'Perl::Critic::Policy::logicLAB::RequireVersionFormat' => '0',
            },
        );

        $build->notes('section_header' => 'POLICIES');

        $build->create_build_script();

    The section of course has to be present.

    Based on your version of perl and your Build.PL requirements, the links
    will be rendered in the following formats:

    Basic:

        #Build.PL
        requires => {
            'Some::Package' => '0',
        }

        #POD, perl all
        =item * L<Some::Package|Some::Package>

    With version:

        #Build.PL
        requires => {
            'Some::Package' => '1.99',
        }

        #POD, perl < 5.12.0
        =item * L<Some::Package|Some::Package>, 1.99

        #POD, perl >= 5.12.0
        =item * L<Some::Package|Some::Package>, L<1\.99\|http://search.cpan.org/dist/Some-Package-1.99/lib/Some/Package.pm>

  ACTION_build
    This is a simple wrapper around the standard action: Module::Build build
    action. It checks whether "ACTION_contents" have been executed, if not
    it executes it.

  get_metadata
    This method has been lifted from Module::Build::Base and altered.

    It sets:

    *   'generated by <package> version <package version>' string in
        META.yml

    For Module::Build::Bundle:

        #Example META.yml
        configure_requires:
            Module::Build::Bundle: 0.01
        generated_by: 'Module::Build::Bundle version 0.01'

  prepare_metadata
    This method has been lifted from Module::Build::Base and altered.

    It sets:

    *   configure_requires: <package>: <version>

  do_create_metafile
    This method has been lifted from Module::Build::Base and altered.

    The method was overwritten to be more testable. The method created the
    relevant META file.

    It passes a more general file parameter for testing instead of a
    hard-coded filename.

DIAGNOSTICS
    *   No <section> section to be replaced

        If the POD to be updated does not contain a placeholder section the
        action will die with the above message.

        The default minimal section should look something like:

            =head1 CONTENTS

            =head1

        Or if you provide your own section_header

            =head1 <section header>

            =head1

CONFIGURATION AND ENVIRONMENT
    The only special configuration necessary is described in the section
    below.

  CONTENTS SECTION
    The module does per default look for the section named: CONTENTS.

    This is the section used in Bundles, this can be overwritten using the
    section parameter.

    For example Perl::Critic::logicLAB uses a section named POLICIES and
    Task::BeLike::JONASBN uses DEPENDENCIES as section header.

    The problem is that the section has to be present or else the contents
    action will throw an error.

    Module::Build::Bundle is primarily aimed at Bundle distributions. Their
    use is however no longer recommended and Task provides a better way.

DEPENDENCIES
    *   perl 5.8.0

    *   Module::Build::Base, part of the Module::Build distribution

INCOMPATIBILITIES
    The distribution requires perl version from 5.8.0 and up, earlier
    versions of perl are not supported.

BUGS AND LIMITATIONS
    Currently Module::Build::Bundle is not able to handle root based
    distributions meaning distributions with a single Perl module located in
    the root directory instead of the lib structure.

    Apart from that there are no known special limitations or bugs at this
    time, but I am certain there are plenty of scenarios is distribution
    packaging the module is not currently handling.

    The module only supports Bundle/Task distributions based on
    Module::Build. The implementation is based on a subclass of
    Module::Build, which can replace Module::Build in your Build.PL (See:
    "SYNOPSIS").

    As described previously in the documentation a section of documentation
    can only replaced. A section with the generated contents cannot be added
    with out a placeholder in the form of designated section title. This
    might be changed in the future.

    Before version 0.11 the designated module was worked on in lib/, I am
    still unsure as to what the right place to do this is. Perhaps *hooking*
    into the build phase is not a good idea at all.

BUG REPORTING
    Please report any bugs or feature requests via:

    *   Github issues: <https://github.com/jonasbn/mbb/issues>

    *   email: bug−module-build-bundle at rt.cpan.org

    *   RT:
        <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Build-Bundle>

TEST AND QUALITY
  TEST COVERAGE
        ---------------------------- ------ ------ ------ ------ ------ ------ ------
        File                           stmt   bran   cond    sub    pod   time  total
        ---------------------------- ------ ------ ------ ------ ------ ------ ------
        lib/Module/Build/Bundle.pm     44.5   18.3   23.0   70.5  100.0  100.0   39.6
        Total                          44.5   18.3   23.0   70.5  100.0  100.0   39.6
        ---------------------------- ------ ------ ------ ------ ------ ------ ------

    The above coverage report is based on release 0.13

QUALITY AND CODING STANDARD
    The code passes Perl::Critic tests a severity: 1 (brutal)

    The following policies have been disabled:

          L<Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint>

    Perl::Critic resource file, can be located in the t/ directory of the
    distribution see F <t/perlcriticrc>

    Perl::Tidy resource file, can be obtained from the following URL:

    *   <https://logiclab.jira.com/wiki/display/OPEN/Perl-Tidy>

DEVELOPMENT
    The Module::Build::Bundle repository is public available on Github, pull
    requests most welcome.

TODO
    *   Exchange the fragile POD handling with Pod::Weaver

    *   Methods lifted from Module::Build::Base, could be backported to
        Module::Build::Base, as patches if these can be implemented in a
        acceptable state.

    Please see:
    <https://logiclab.jira.com/browse/MBB#selectedTab=com.atlassian.jira.plu
    gin.system.project%3Aroadmap-panel>

SEE ALSO
    *   Task

    *   TaskBeLike::JONASBN

    *   Perl::Critic::logicLAB

    *   CPAN

    *   CPAN::Bundle
        <http://cpansearch.perl.org/src/ANDK/CPAN-1.9402/lib/CPAN/Bundle.pm>

    *   <https://logiclab.jira.com/wiki/display/OPEN/Module-Build-Bundle>

MOTIVATION
    The motivation for development of this module was driven by two things.

    *   The joy of fooling around with Module::Build

    *   The need for automating the documentation generation

    I have a few perks and one of them is that I never get to automate stuff
    until very late and I always regret that. So when I released
    Bundle::JONASBN, now Task::BeLike::JONASBN I thought I might aswell get
    it automated right away.

    This module lived for a long time as a part of Bundle::JONASBN but then
    I needed it for some other distributions, so I decided to separate it
    out.

ACKNOWLEDGEMENTS
    *   Adam Kennedy (ADAMK) author of Task, a very basic and simple
        solution

    *   The Module::Build developers

    *   Lars Dɪᴇᴄᴋᴏᴡ (DAXIM) for reporting RT:83754, resulting in release
        0.11

    *   Andreas J. König (ANDK) for reporting RT:82128, included in release
        0.10

AUTHOR
    *   Jonas B. Nielsen (jonasbn) "<jonasbn@cpan.org>"

LICENSE AND COPYRIGHT
    Copyright 2010-2015 jonasbn, all rights reserved.

    Module::Build::Bundle is released under the Artistic License 2.0

