Module::Build::Bundle - subclass for supporting Tasks and Bundles
This documentation describes version 0.11
#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
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.
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>
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.
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'
It sets:
'generated by <package> version <package version>' string in META.yml
configure_requires: <package>: <version>
#Example META.yml configure_requires: Module::Build::Bundle: 0.01 generated_by: 'Module::Build::Bundle version 0.01'
The method was overwritten to be more testable. The method created the relevant META file.
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
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.
perl 5.6.0
Module::Build::Base, part of the Module::Build distribution
The distribution requires perl version from 5.6.0 and up.
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.
Please report any bugs or feature requests via:
email: bug−module-build-bundle at rt.cpan.org
HTTP: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Build-Bundle
---------------------------- ------ ------ ------ ------ ------ ------ ------ 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
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 <t/perlcriticrc>
Perl::Tidy resource file, can be obtained from the following URL:
https://logiclab.jira.com/wiki/display/OPEN/Perl-Tidy
Please see: https://logiclab.jira.com/browse/MBB#selectedTab=com.atlassian.jira.plugin.system.project%3Aroadmap-panel
Task
TaskBeLike::JONASBN
Perl::Critic::logicLAB
CPAN
CPAN::Bundle
https://logiclab.jira.com/wiki/display/OPEN/Module-Build-Bundle
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.
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
Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org>
<jonasbn@cpan.org>
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.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'bug−module-build-bundle'. Assuming UTF-8
To install Module::Build::Bundle, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Build::Bundle
CPAN shell
perl -MCPAN -e shell install Module::Build::Bundle
For more information on module installation, please visit the detailed CPAN module installation guide.