Dist::Zilla::Plugin::OptionalFeature - Specify prerequisites for optional features in your distribution
version 0.023
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).
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.
-phase
runtime
-relationship
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:
[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.
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.
optional_feature
recommends
suggests
-prompt
=prompt
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.
PERL_MM_USE_DEFAULT=1
dzil build
-name
The name of the optional feature, to be presented to the user. Can also be extracted from the plugin name.
-description
The description of the optional feature, to be presented to the user. Defaults to the feature name, if not provided.
-always_recommend
If set with a true value, the prerequisites are added to the distribution's metadata as recommended prerequisites (e.g. cpanminus will install recommendations with --with-recommends, even when running non-interactively).
--with-recommends
Defaults to false, but I recommend you turn this on.
false
-always_suggest
(Available since version 0.022)
If set with a true value, the prerequisites are added to the distribution's metadata as suggested prerequisites.
Defaults to the inverse of -always_recommend.
-require_develop
(Available since version 0.011)
If set with a true value, the prerequisites are added to the distribution's metadata as develop requires prerequisites (e.g. cpanminus will install recommendations with --with-develop, even when running non-interactively).
--with-develop
Defaults to true.
true
(Available since version 0.017)
If set with a true value, Makefile.PL is modified to include interactive prompts.
Default is true if -relationship is requires. false otherwise.
-check_prereqs
(Available since version 0.021 as -load_prereqs, 0.022 as its present name)
If set, and -prompt is also set, the prerequisites to be added by the feature are checked for in the Perl installation; if the requirements are already met, then the feature is automatically added.
Default is true.
-default
(Available since version 0.006)
If set with a true value, non-interactive installs will automatically fold the feature's prerequisites into the regular prerequisites.
Note that at the time of this feature's creation (September 2013), there is no compliant CPAN client yet, as it invents a new x_default field in metadata under optional_feature (thanks, miyagawa!)
x_default
The phase of the prequisite(s). Should be one of: build, test, runtime, or develop.
Default: runtime
-type
The relationship of the prequisite(s). Should be one of: requires, recommends, suggests, or conflicts.
Default: requires
"optional_features" in CPAN::Meta::Spec
"features, feature (Module::Install::Metadata)" in Module::Install::API
Bugs may be submitted through the RT bug tracker (or bug-Dist-Zilla-Plugin-OptionalFeature@rt.cpan.org).
There is also a mailing list available for users of this distribution, at http://dzil.org/#mailing-list.
There is also an irc channel available for users of this distribution, at #distzilla on irc.perl.org.
#distzilla
irc.perl.org
I am also usually active on irc, as 'ether' at irc.perl.org.
Karen Etheridge <ether@cpan.org>
Kent Fredric <kentnl@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.
To install Dist::Zilla::Plugin::OptionalFeature, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Plugin::OptionalFeature
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Plugin::OptionalFeature
For more information on module installation, please visit the detailed CPAN module installation guide.