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.plugin.system.project%3Aroadmap-panel

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

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:

Around line 474:: 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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

FEATURES

SUBROUTINES/METHODS

ACTION_contents

ACTION_build

create_mymeta

get_metadata

do_create_metafile

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

CONTENTS SECTION

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

BUG REPORTING

TEST AND QUALITY

TEST COVERAGE

QUALITY AND CODING STANDARD

DEVELOPMENT

TODO

SEE ALSO

MOTIVATION

ACKNOWLEDGEMENTS

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions