NAME Module::Build::Bundle - subclass for supporting Tasks and Bundles VERSION This documentation describes version 0.11 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 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), ', 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 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' 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. 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 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: * email: bug−module-build-bundle at rt.cpan.org * HTTP: TEST AND QUALITY TEST COVERAGE ---------------------------- ------ ------ ------ ------ ------ ------ ------ File stmt bran cond sub pod time total ---------------------------- ------ ------ ------ ------ ------ ------ ------ lib/Module/Build/Bundle.pm 48.5 13.9 14.3 84.2 100.0 100.0 45.7 Total 48.5 13.9 14.3 84.2 100.0 100.0 45.7 ---------------------------- ------ ------ ------ ------ ------ ------ ------ The above coverage report is based on release 0.11 QUALITY AND CODING STANDARD The code passes Perl::Critic tests a severity: 1 (brutal) The following policies have been disabled: Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint Perl::Critic resource file, can be located in the t/ directory of the distribution see F Perl::Tidy resource file, can be obtained from the following URL: * DEVELOPMENT TODO Please see: SEE ALSO * Task * TaskBeLike::JONASBN * Perl::Critic::logicLAB * CPAN * * 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 * 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) "" LICENSE AND COPYRIGHT Copyright 2010-2013 jonasbn, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.