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), <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.
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'
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'
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> 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
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:
<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 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 <t/perlcriticrc>
Perl::Tidy resource file, can be obtained from the following URL:
* <https://logiclab.jira.com/wiki/display/OPEN/Perl-Tidy>
DEVELOPMENT
TODO
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>
* <https://logiclab.jira.com/wiki/display/OPEN/Module-Build-Bundle>
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) "<jonasbn@cpan.org>"
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.