NAME Module::Build::Bundle - subclass for supporting Tasks and Bundles VERSION This documentation describes version 0.01 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), ', 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 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), ', 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 With version: #Build.PL requires => { 'Some::Package' => '1.99', } #POD, perl < 5.12.0 =item * L, 1.99 #POD, perl >= 5.12.0 =item * L, 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 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' get_metadata This method has been lifted from Module::Build::Base and altered. It sets: * 'generated by version ' string in META.yml * configure_requires: : 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 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
=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 Task::BeLike::JONASBN 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 Module::Build 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 Task::BeLike::JONASBN::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 AUTHOR * Jonas B. Nielsen (jonasbn) `' 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.