Dist::Zilla::Plugin::ModuleBuild::Custom(3pm)

1Dist::Zilla::Plugin::MoUdsuelreBCuoinltdr:i:bCuutDseitdsotmP:(e:3rZ)lilDloac:u:mPelnutgaitni:o:nModuleBuild::Custom(3)
2
3
4

NAME

6       Dist::Zilla::Plugin::ModuleBuild::Custom - Allow a dist to have a
7       custom Build.PL
8

VERSION

10       This document describes version 4.26 of
11       Dist::Zilla::Plugin::ModuleBuild::Custom, released December 17, 2017 as
12       part of Dist-Zilla-Plugins-CJM version 6.000.
13

SYNOPSIS

15       In dist.ini:
16
17         [ModuleBuild::Custom]
18         mb_version = 0.34  ; the default comes from the ModuleBuild plugin
19
20       In your Build.PL:
21
22         use Module::Build;
23
24         my %module_build_args = (
25           module_name => 'Foo::Bar',
26         ##{ $plugin->get_prereqs(1) ##}
27         ##{ $plugin->get_default('share_dir') ##}
28         );
29
30         unless ( eval { Module::Build->VERSION(0.4004) } ) {
31           my $tr = delete $module_build_args{test_requires};
32           my $br = $module_build_args{build_requires};
33           for my $mod ( keys %$tr ) {
34             if ( exists $br->{$mod} ) {
35               $br->{$mod} = $tr->{$mod} if $tr->{$mod} > $br->{$mod};
36             }
37             else {
38               $br->{$mod} = $tr->{$mod};
39             }
40           }
41         } # end unless Module::Build is 0.4004 or newer
42
43         my $builder = Module::Build->new(%module_build_args);
44         $builder->create_build_script;
45
46       Of course, your Build.PL doesn't need to look exactly like this.  If
47       you can require Module::Build 0.4004, then you can remove the "unless
48       eval" section.  If you're not using "share_dir", you can remove that
49       line.
50
51       And if you're not adding your own code to Build.PL, you don't need this
52       plugin.
53

DESCRIPTION

55       This plugin is for people who need something more complex than the
56       auto-generated Makefile.PL or Build.PL generated by the MakeMaker or
57       ModuleBuild plugins.
58
59       It is a subclass of the ModuleBuild plugin, but it does not write a
60       Build.PL for you.  Instead, you write your own Build.PL, which may do
61       anything Module::Build is capable of (except generate a compatibility
62       Makefile.PL).
63
64       This plugin will process Build.PL as a template (using Text::Template),
65       which allows you to add data from Dist::Zilla to the version you
66       distribute (if you want).  The template delimiters are "##{" and "##}",
67       because that makes them look like comments.  That makes it easier to
68       have a Build.PL that works both before and after it is processed as a
69       template.
70
71       This is particularly useful for XS-based modules, because it can allow
72       you to build and test the module without the overhead of "dzil build"
73       after every small change.
74
75       The template may use the following variables:
76
77       $dist
78           The name of the distribution.
79
80       $meta
81           The hash of metadata (in META 1.4 format) that will be stored in
82           META.yml.
83
84       $meta2
85           The hash of metadata (in META 2 format) that will be stored in
86           META.json.
87
88       $plugin
89           The ModuleBuild::Custom object that is processing the template.
90
91       $version
92           The distribution's version number.
93
94       $zilla
95           The Dist::Zilla object that is creating the distribution.
96
97   Using ModuleBuild::Custom with AutoPrereqs
98       If you are using the AutoPrereqs plugin, then you will probably want to
99       set its "configure_finder" to a FileFinder that includes Build.PL.  You
100       may also want to set this plugin's "mb_version" parameter to 0 and
101       allow AutoPrereqs to get the version from your "use Module::Build"
102       line.
103
104       Example dist.ini configuration:
105
106         [ModuleBuild::Custom]
107         mb_version = 0 ; AutoPrereqs gets actual version from Build.PL
108
109         [FileFinder::ByName / :BuildPL]
110         file = Build.PL
111
112         [AutoPrereqs]
113         :version = 4.300005 ; need configure_finder
114         configure_finder = :BuildPL
115         ; Add next line if your Build.PL uses modules you ship in inc/
116         configure_finder = :IncModules
117
118       Then in your Build.PL you'd say:
119
120         use Module::Build 0.28; # or whatever version you need
121

METHODS

123   get_default
124         $plugin->get_default(qw(key1 key2 ...))
125
126       A template can call this method to extract the specified key(s) from
127       the default Module::Build arguments created by the normal ModuleBuild
128       plugin and have them formatted into a comma-separated list suitable for
129       a hash constructor or a method's parameter list.
130
131       If any key has no value (or its value is an empty hash or array ref) it
132       will be omitted from the list.  If all keys are omitted, the empty
133       string is returned.  Otherwise, the result always ends with a comma.
134
135       The most common usage would be
136
137           ##{ $plugin->get_default('share_dir') ##}
138
139   get_meta
140         $plugin->get_meta(qw(key1 key2 ...))
141
142       A template can call this method to extract the specified key(s) from
143       "distmeta" and have them formatted into a comma-separated list suitable
144       for a hash constructor or a method's parameter list.  The keys (and the
145       returned values) are from the META 1.4 spec, because that's what
146       Module::Build uses in its API.
147
148       If any key has no value (or its value is an empty hash or array ref) it
149       will be omitted from the list.  If all keys are omitted, the empty
150       string is returned.  Otherwise, the result always ends with a comma.
151
152   get_prereqs
153         $plugin->get_prereqs($api_version)
154
155       This returns all the keys that describe the distribution's
156       prerequisites.  The $api_version indicates what keys the template can
157       handle.  The currently defined values are:
158
159       0 (or undef)
160               This is equivalent to
161
162                 $plugin->get_meta(qw(build_requires configure_requires requires
163                                      recommends conflicts))
164
165       1       This adds "test_requires" as a separate key (which requires
166               Dist::Zilla 4.300032 or later).  It's equivalent to
167
168                 $plugin->get_default(qw(build_requires configure_requires requires
169                                         test_requires recommends conflicts))
170
171               Your Build.PL should either require Module::Build 0.4004, or
172               fold test_requires into build_requires if an older version is
173               used (as shown in the SYNOPSIS).
174

DEPENDENCIES

180       ModuleBuild::Custom requires Dist::Zilla (6 or later) and
181       Text::Template.  I also recommend applying Template_strict.patch to
182       Text::Template.  This will add support for the STRICT option, which
183       will help catch errors in your templates.
184

INCOMPATIBILITIES

186       You must not use this in conjunction with the ModuleBuild plugin.
187

BUGS AND LIMITATIONS

189       No bugs have been reported.
190

AUTHOR

192       Christopher J. Madsen  "<perl AT cjmweb.net>"
193
194       Please report any bugs or feature requests to
195       "<bug-Dist-Zilla-Plugins-CJM AT rt.cpan.org>" or through the web
196       interface at
197       <http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugins-CJM>.
198
199       You can follow or contribute to Dist-Zilla-Plugins-CJM's development at
200       <https://github.com/madsen/dist-zilla-plugins-cjm>.
201

COPYRIGHT AND LICENSE

203       This software is copyright (c) 2017 by Christopher J. Madsen.
204
205       This is free software; you can redistribute it and/or modify it under
206       the same terms as the Perl 5 programming language system itself.
207

DISCLAIMER OF WARRANTY

209       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
210       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
211       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
212       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
213       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
214       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
215       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
216       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
217       NECESSARY SERVICING, REPAIR, OR CORRECTION.
218
219       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
220       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
221       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE
222       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
223       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
224       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
225       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
226       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
227       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
228       DAMAGES.
229
230
231
232perl v5.34.0                      20D2i1s-t0:7:-Z2i2lla::Plugin::ModuleBuild::Custom(3)