Karen Etheridge > Dist-Zilla-Plugin-OptionalFeature > Dist::Zilla::Plugin::OptionalFeature

Download:
Dist-Zilla-Plugin-OptionalFeature-0.014.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.014   Source  

NAME ^

Dist::Zilla::Plugin::OptionalFeature - Specify prerequisites for optional features in your distribution

VERSION ^

version 0.014

SYNOPSIS ^

In your dist.ini:

    [OptionalFeature / XS_Support]
    -description = XS implementation (faster, requires a compiler)
    Foo::Bar::XS = 1.002

DESCRIPTION ^

This plugin provides a mechanism for specifying prerequisites for optional features in metadata, which should cause CPAN clients to interactively prompt you regarding these features at install time (assuming interactivity is turned on: e.g. cpanm --interactive Foo::Bar).

The feature name and description are required. The name can be extracted from the plugin name.

You can specify requirements for different phases and relationships with:

    [OptionalFeature / Feature_name]
    -description = description
    -phase = test
    -relationship = requires
    Fitz::Fotz    = 1.23
    Text::SoundEx = 3

If not provided, -phase defaults to runtime, and -relationship to requires.

To specify feature requirements for multiple phases, provide them as separate plugin configurations (keeping the feature name and description constant):

    [OptionalFeature / Feature_name]
    -description = description
    -phase = runtime
    Foo::Bar = 0

    [OptionalFeature / Feature_name]
    -description = description
    -phase = test
    Foo::Baz = 0

It is possible that future versions of this plugin may allow a more compact way of providing sophisticated prerequisite specifications.

If the plugin name is the CamelCase concatenation of a phase and relationship (or just a relationship), it will set those parameters implicitly. If you use a custom name, but it does not specify the relationship, and you didn't specify either or both of -phase or -relationship, these values default to runtime and requires respectively.

The example below is equivalent to the synopsis example above, except for the name of the resulting plugin:

    [OptionalFeature]
    -name = XS_Support
    -description = XS implementation (faster, requires a compiler)
    -phase = runtime
    -relationship = requires
    Foo::Bar::XS = 1.002

NOTE: It is advised that you only specify one prerequisite for a given feature -- and if necessary, create a separate distribution to encapsulate the code needed to make that feature work (along with all of its dependencies). This allows external projects to declare a prerequisite not just on your distribution, but also a particular feature of that distribution.

CONFIG OPTIONS ^

This is mostly a restating of the information above.

SUPPORT ^

Bugs may be submitted through the RT bug tracker (or bug-Dist-Zilla-Plugin-OptionalFeature@rt.cpan.org). I am also usually active on irc, as 'ether' at irc.perl.org.

SEE ALSO ^

AUTHOR ^

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: