NAME

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

VERSION

This documentation describes version 0.06

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
    
=head1 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 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 the distribution targetted.

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

create_mymeta

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

It sets the:

• 'generated by <package> version <package version>' string in MYMETA.yml

For Module::Build::Bundle:

    #Example MYMETA.yml
    configure_requires:
        Module::Build::Bundle: 0.01
    generated_by: 'Module::Build::Bundle version 0.01'
    
=head2 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
• configure_requires: <package>: <version>

For Module::Build::Bundle:

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

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

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 the Task::BeLike::JONASBN manpage uses DEPENDENCIES.

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.6.0
• Module::Build::Base, part of the the Module::Build manpage distribution

INCOMPATIBILITIES

The distribution requires perl version from 5.6.0 and up.

BUGS AND LIMITATIONS

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

Currently 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 (See: SYNOPSIS).

SEE ALSO

• Task
• TaskBeLike::JONASBN
• Perl::Critic::logicLAB
• CPAN
• http://cpansearch.perl.org/src/ANDK/CPAN-1.9402/lib/CPAN/Bundle.pm

MOTIVATION

The motivation 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 the Task::BeLike::JONASBN::Task::BeLike::JONASBN manpage 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 the Module::Build manpage developers

AUTHOR

• Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2010 jonasbn, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.