jonasbn > Module-Build-Bundle-0.11 > Module::Build::Bundle

Download:
Module-Build-Bundle-0.11.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.11   Source   Latest Release: Module-Build-Bundle-0.12

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

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:

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:

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 ^

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 ^

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:

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:

DEVELOPMENT ^

TODO ^

Please see: https://logiclab.jira.com/browse/MBB#selectedTab=com.atlassian.jira.plugin.system.project%3Aroadmap-panel

SEE ALSO ^

MOTIVATION ^

The motivation was driven by two things.

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 ^

AUTHOR ^

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.

syntax highlighting: