Dist::Zilla::Plugin::DynamicPrereqs(3)

NAME
Dist::Zilla::Plugin::DynamicPrereqs - Specify dynamic (user-side) prerequisites for your distribution

VERSION
version 0.040

SYNOPSIS
In your dist.ini:

    [DynamicPrereqs]
    -condition = has_module('Role::Tiny')
    -condition = !want_pp()
    -condition = can_xs()
    -body = requires('Role::Tiny', '1.003000')

or:

    [DynamicPrereqs]
    -delimiter = |
    -raw = |test_requires('Devel::Cover')
    -raw = |    if $ENV{EXTENDED_TESTING} or is_smoker();

or:

    [DynamicPrereqs]
    -raw_from_file = Makefile.args      # code snippet in this file

DESCRIPTION
This is a Dist::Zilla plugin that inserts code into your Makefile.PL to indicate dynamic (installer-side) prerequisites.

Code is inserted immediately after the declarations for %WriteMakefileArgs and %FallbackPrereqs, before they are conditionally modified (when an older ExtUtils::MakeMaker is installed). This gives you an opportunity to add to the "WriteMakefile" arguments: "PREREQ_PM", "BUILD_REQUIRES", and "TEST_REQUIRES", and therefore modify the prerequisites in the user's MYMETA.yml and MYMETA.json based on conditions found on the user's system.

The "dynamic_config" field in metadata is already set for you.

You could potentially use this plugin for performing other modifications in Makefile.PL other than user-side prerequisite modifications, but I can't think of a situation where this makes sense. Contact me if you have any ideas!

Only Makefile.PL modification is supported at this time. This author considers the use of Module::Build to be questionable in all circumstances, and Module::Build::Tiny does not (yet?) support dynamic configuration.

BE VIGILANT!
You are urged to check the generated Makefile.PL for sanity, and to run it at least once to validate its syntax. Although every effort is made to generate valid and correct code, mistakes can happen, so verification is needed before shipping.

Please also see the other warnings later in this document.

CONFIGURATION OPTIONS

  "-raw"

  "-body"
The code to be inserted; must be valid and complete perl statements. You can reference and modify the already-declared %WriteMakefileArgs and %FallbackPrereqs variables, as inserted into Makefile.PL by Dist::Zilla::Plugin::MakeMaker and subclasses (e.g. Dist::Zilla::Plugin::MakeMaker::Awesome since Dist::Zilla 5.001.

This option can be used more than once; lines are added in the order in which they are provided.

If you use external libraries in the code you are inserting, you must add these modules to "configure_requires" prereqs in metadata (e.g. via "[Prereqs / ConfigureRequires]" in your dist.ini).

"-body" first became available in version 0.018.

  "-delimiter"
(Available since version 0.007)

A string, usually a single character, which is stripped from the beginning of all "-raw"/"-body" lines. This is because the INI file format strips all leading whitespace from option values, so including this character at the front allows you to use leading whitespace in an option string, so you can indent blocks of code properly.

  "-raw_from_file"
(Available since version 0.010)

  "-body_from_file"
(Available since version 0.018)

A filename that contains the code to be inserted; must be valid and complete perl statements, as with "-raw"/"-body" above. This file must be part of the build, but it is pruned from the built distribution.

  "-condition"
(Available since version 0.014)

A perl expression to be included in the condition statement in the Makefile.PL. Multiple "-condition"s can be provided, in which case they are ANDed together to form the final condition statement. (You must appropriately parenthesize each of your conditions to ensure correct order of operations.) Any use of recognized subroutines will cause their definitions to be included automatically (see "AVAILABLE SUBROUTINE DEFINITIONS", below).

When combined with "-raw"/"-body" lines, the condition is placed first in a "if" statement, and the "-raw"/"-body" lines are contained as the body of the block. For example:

    [DynamicPrereqs]
    -condition = "$]" > '5.020'
    -body = requires('Role::Tiny', '1.003000')

results in the Makefile.PL snippet (note that whitespace is not added, in case this affects the parsing:

    if ("$]" > '5.020') {
    requires('Role::Tiny', '1.003000')
    }

  "-include_sub"
(Available since version 0.010; rendered unnecessary in 0.016 (all definitions are now included automatically, when used).

AVAILABLE SUBROUTINE DEFINITIONS
A number of helper subroutines are available for use within your code inserted via "-body", "-body_from_file", "-raw", "-raw_from_file", or "-condition" clauses. When used, their definition(s) will be included automatically in Makefile.PL (as well as those of any other subroutines they call); necessary prerequisite modules will be added to "configure requires" metadata.

Unless otherwise noted, these all became available in version 0.010. Available subs are:

•   "prompt_default_yes($message)" - takes a string (appending "[Y/n]" to it), returns a boolean; see "prompt" in ExtUtils::MakeMaker

•   "prompt_default_no($message)" - takes a string (appending "[y/N]" to it), returns a boolean; see "prompt" in ExtUtils::MakeMaker

•   "parse_args()" - returns the hashref of options that were passed as arguments to "perl Makefile.PL"

•   "can_xs()" - XS capability testing via ExtUtils::HasCompiler (don't forget to also check "want_pp"!) Available in this form since 0.029.

•   "can_cc()" - can we locate a (the) C compiler

•   "can_run()" - check if we can run some command

•   "is_miniperl()" - returns true if the current perl is miniperl (this may affect your ability to run XS code) Available since 0.033.

•   "can_use($module [, $version ])" - checks if a module (optionally, at a specified version) can be loaded. (If you don't want to load the module, you should use "has_module", see below.)

•   "has_module($module [, $version_or_range ])" - checks if a module (optionally, at a specified version or matching a version range) is available in %INC. Does not load the module, so is safe to use with modules that have side effects when loaded. When passed a second argument, returns true or false; otherwise, returns undef or the module's $VERSION. Note that for extremely simple usecases (module has no side effects when loading, and no explicit version is needed), it can be simpler and more backcompat-friendly to simply do: "eval { require Foo::Bar }". (Current API available since version 0.015.)

•   "is_smoker()" - is the installation on a smoker machine?

•   "is_interactive()" - is the installation in an interactive terminal?

•   "is_trial()" - is the release a -TRIAL or _XXX-versioned release?

•   "is_os($os, ...)" - true if the OS is any of those listed

•   "isnt_os($os, ...)" - true if the OS is none of those listed

•   "maybe_command" - actually a monkeypatch to "MM->maybe_command" (please keep using the fully-qualified form) to work in Cygwin

•   "runtime_requires($module [, $version ])" - adds the module to runtime prereqs (as a shorthand for editing the hashes in Makefile.PL directly). Added in 0.016.

•   "requires($module [, $version ])" - alias for "runtime_requires". Added in 0.016.

•   "build_requires($module [, $version ])" - adds the module to build prereqs (as a shorthand for editing the hashes in Makefile.PL directly). Added in 0.016.

•   "test_requires($module [, $version ])" - adds the module to test prereqs (as a shorthand for editing the hashes in Makefile.PL directly). Added in 0.016.

•   "want_pp()" - true if the user or CPAN client explicitly specified "PUREPERL_ONLY" (indicating that no XS-requiring modules or code should be installed). false if the user has explicitly specified "PUREPERL_ONLY" as 0. undef if no preference was specified.

•   "want_xs()" - true if "PUREPERL_ONLY" was specified as 0, or if it was not specified and compiling XS modules is possible (checked via can_xs).

WARNING: INCOMPLETE SUBROUTINE IMPLEMENTATIONS!
The implementations for some subroutines (in particular, "can_xs", "can_cc" and "can_run" are still works in progress, incompatible with some architectures and cannot yet be considered a suitable generic solution. Until we are more confident in their implementations, a warning will be printed (to the distribution author) upon use, and their use is not advised without prior consultation with the author and other members of the Perl Toolchain Gang (see "#toolchain" on "irc.perl.org" <irc://irc.perl.org/#toolchain>).

WARNING: UNSTABLE API!
This plugin is still undergoing active development, and the interfaces will change and grow as I work through the proper way to do various things. As I make changes, I will be using metacpan's reverse dependencies list <https://metacpan.org/requires/distribution/Dist-Zilla-Plugin-DynamicPrereqs> and <http://grep.cpan.me> to find and fix any upstream users, but I obviously cannot do this for DarkPAN users. Regardless, please contact me (see below) and I will keep you directly advised of interface changes.

Future planned features:

•   better compiler detection and conditional XS code inclusion

•   interoperability with the [CPANFile] plugin (generation of dynamic prerequisites into a cpanfile)

•   something like "is_perl_at_least('5.008001')" for testing $]

•   inlining of sub content for some checks, to allow constant folding (e.g. $^O and $] checks)

LIMITATIONS
It is not possible, given the current features of ExtUtils::MakeMaker, to have dynamic prerequisites using the "recommends", "suggests" or "conflicts" types. (This is because these get added via the "META_ADD" or "META_MERGE" Makefile arguments, and these are ignored for the generation of MYMETA.json.)

SEE ALSO

•   Dist::Zilla::Plugin::MakeMaker

•   "Using Attributes and Parameters" in ExtUtils::MakeMaker

•   Dist::Zilla::Plugin::OSPrereqs

•   Dist::Zilla::Plugin::PerlVersionPrereqs

•   Module::Install::Can

SUPPORT
Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-DynamicPrereqs> (or bug-Dist-Zilla-Plugin-DynamicPrereqs@rt.cpan.org <mailto:bug-Dist-Zilla-Plugin-DynamicPrereqs@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" <irc://irc.perl.org/#distzilla>.

I am also usually active on irc, as 'ether' at "irc.perl.org" and "irc.libera.chat".

AUTHOR
Karen Etheridge <ether@cpan.org>

CONTRIBUTORS

•   Graham Knop <haarg@haarg.org>

•   Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENCE
This software is copyright (c) 2014 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.