Module::Build::Bundle - subclass for supporting Tasks and Bundles
This documentation describes version 0.17
#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:
- 'generated by version ' string in
META.yml
For Module::Build::Bundle:
#Example META.yml
configure_requires:
Module::Build::Bundle: 0.01
generated_by: 'Module::Build::Bundle version 0.01'
This method has been lifted from Module::Build::Base and altered.
It sets:
- configure_requires: :
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.
It passes a more general file parameter for testing instead of a hard-coded filename.
Required overwritten by Module::Build, when subclassing.
Ref: https://metacpan.org/pod/distribution/Module-Build/lib/Module/Build/API.pod
-
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 <section header> =head1
The only special configuration necessary is described in the section below.
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 as section header.
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.8.0
- Module::Build::Base, part of the Module::Build distribution
The distribution requires perl version from 5.8.0 and up, earlier versions of perl are not supported.
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:
- Github issues: https://github.com/jonasbn/mbb/issues
- email: bug−module-build-bundle at rt.cpan.org
- RT: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Build-Bundle
---------------------------- ------ ------ ------ ------ ------ ------ ------
File stmt bran cond sub pod time total
---------------------------- ------ ------ ------ ------ ------ ------ ------
lib/Module/Build/Bundle.pm 44.5 18.3 23.0 70.5 100.0 100.0 39.6
Total 44.5 18.3 23.0 70.5 100.0 100.0 39.6
---------------------------- ------ ------ ------ ------ ------ ------ ------
The above coverage report is based on release 0.13
The code passes Perl::Critic tests a severity: 1 (brutal)
The following policies have been disabled:
L<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:
The Module::Build::Bundle repository is public available on Github, pull requests most welcome.
- Exchange the fragile POD handling with Pod::Weaver
- Methods lifted from Module::Build::Base, could be backported to Module::Build::Base, as patches if these can be implemented in a acceptable state.
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 for development of this module 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 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
- Slaven Rezić for reporting issue #2
- Jonas B. Nielsen (jonasbn)
<jonasbn@cpan.org>
Copyright 2010-2015 jonasbn, all rights reserved.
Module::Build::Bundle is released under the Artistic License 2.0