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



Annotate this POD



Open  0
View/Report Bugs
Module Version: 0.021   Source  


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


version 0.021


In your dist.ini:

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


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

NOTE: this doesn't seem to work properly with CPAN::Meta::Merge (used in Dist::Zilla since version 5.022).

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:

    -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.


At the moment it doesn't appear that any CPAN clients properly support optional_feature metadata and interactively prompt the user with the information therein. Therefore, prompting is added directly to Makefile.PL when the -relationship is requires. (It doesn't make much sense to prompt for recommends or suggests features, so prompting is omitted here.) You can also enable or disable this explicitly with the -prompt option. The prompt feature can only be used with Makefile.PL. If a Build.PL is detected in the build and =prompt is set, the build will fail.

As with any other interactive features, the installing user can bypass the prompts with PERL_MM_USE_DEFAULT=1. You may want to set this when running dzil build.


This is mostly a restating of the information above.


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.



Karen Etheridge <ether@cpan.org>


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.


Kent Fredric <kentnl@cpan.org>

syntax highlighting: