1Dist::Zilla::Plugin::MaUkseeMrakCeorn:t:rCiubsuttoemdD(i3Ps)etr:l:ZDiolcluam:e:nPtlautgiionn::MakeMaker::Custom(3)
2
6 Dist::Zilla::Plugin::MakeMaker::Custom - Allow a dist to have a custom
7 Makefile.PL
8
10 This document describes version 4.26 of
11 Dist::Zilla::Plugin::MakeMaker::Custom, released December 17, 2017 as
12 part of Dist-Zilla-Plugins-CJM version 6.000.
13
15 In dist.ini:
16 [MakeMaker::Custom]
18 eumm_version = 0.34 ; the default comes from the MakeMaker plugin
19 In your Makefile.PL:
21 use ExtUtils::MakeMaker;
23 ##{ $share_dir_code{preamble} || '' ##}
25 my %args = (
27 NAME => "My::Module",
28 ##{ $plugin->get_default(qw(ABSTRACT AUTHOR LICENSE VERSION)) ##}
29 ##{ $plugin->get_prereqs(1) ##}
30 );
31 unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) {
33 my $tr = delete $args{TEST_REQUIRES};
34 my $br = $args{BUILD_REQUIRES};
35 for my $mod ( keys %$tr ) {
36 if ( exists $br->{$mod} ) {
37 $br->{$mod} = $tr->{$mod} if $tr->{$mod} > $br->{$mod};
38 }
39 else {
40 $br->{$mod} = $tr->{$mod};
41 }
42 }
43 } # end unless ExtUtils::MakeMaker is 6.63_03 or newer
44 unless ( eval { ExtUtils::MakeMaker->VERSION(6.56) } ) {
46 my $br = delete $args{BUILD_REQUIRES};
47 my $pp = $args{PREREQ_PM};
48 for my $mod ( keys %$br ) {
49 if ( exists $pp->{$mod} ) {
50 $pp->{$mod} = $br->{$mod} if $br->{$mod} > $pp->{$mod};
51 }
52 else {
53 $pp->{$mod} = $br->{$mod};
54 }
55 }
56 } # end unless ExtUtils::MakeMaker is 6.56 or newer
57 delete $args{CONFIGURE_REQUIRES}
59 unless eval { ExtUtils::MakeMaker->VERSION(6.52) };
60 delete $args{LICENSE}
62 unless eval { ExtUtils::MakeMaker->VERSION(6.31) };
63 WriteMakefile(%args);
65 ##{ $share_dir_code{postamble} || '' ##}
67 Of course, your Makefile.PL doesn't need to look exactly like this. If
69 you increase the minimum version of ExtUtils::MakeMaker, you can remove
70 any "unless eval" sections whose version test is less than or equal to
71 "eumm_version". If you're not using "share_dir", you can remove those
72 lines.
73 And if you're not adding your own code to Makefile.PL, you don't need
75 this plugin.
76
78 This plugin is for people who need something more complex than the
79 auto-generated Makefile.PL or Build.PL generated by the MakeMaker or
80 ModuleBuild plugins.
81 It is a subclass of the MakeMaker plugin, but it does not write a
83 Makefile.PL for you. Instead, you write your own Makefile.PL, which
84 may do anything ExtUtils::MakeMaker is capable of.
85 This plugin will process Makefile.PL as a template (using
87 Text::Template), which allows you to add data from Dist::Zilla to the
88 version you distribute (if you want). The template delimiters are
89 "##{" and "##}", because that makes them look like comments. That
90 makes it easier to have a Makefile.PL that works both before and after
91 it is processed as a template.
92 This is particularly useful for XS-based modules, because it can allow
94 you to build and test the module without the overhead of "dzil build"
95 after every small change.
96 The template may use the following variables:
98 %default_args
100 The hash of arguments for WriteMakefile generated by the normal
101 MakeMaker plugin.
102 $dist
104 The name of the distribution.
105 $eumm_version
107 The minimum version of ExtUtils::MakeMaker required (from the
108 "eumm_version" attribute of this plugin).
109 %meta
111 The hash of metadata (in META 2 format) that will be stored in
112 META.json.
113 $perl_prereq
115 The minimum version of Perl required (from the prerequisites in the
116 metadata). May be "undef". Equivalent to
117 $default_args{MIN_PERL_VERSION}.
118 $plugin
120 The MakeMaker::Custom object that is processing the template.
121 %share_dir_code
123 A hash of strings containing the code for loading
124 "File::ShareDir::Install" (if it's used by this dist). Put
125 "##{ $share_dir_code{preamble} || '' ##}" after the
126 "use ExtUtils::MakeMaker" line, and put
127 "##{ $share_dir_code{postamble} || '' ##}" after the
128 "WriteMakefile" call. (You can omit the "|| ''" if you're sure the
129 dist is using File::ShareDir.
130 For backwards compatibility, this code is also available in the
132 array @share_dir_block, but you should update your templates to use
133 %share_dir_code instead.
134 $version
136 The distribution's version number.
137 $zilla
139 The Dist::Zilla object that is creating the distribution.
140 Using MakeMaker::Custom with AutoPrereqs
142 If you are using the AutoPrereqs plugin, then you will probably want to
143 set its "configure_finder" to a FileFinder that includes Makefile.PL.
144 You may also want to set this plugin's "eumm_version" parameter to 0
145 and allow AutoPrereqs to get the version from your
146 "use ExtUtils::MakeMaker" line.
147 Example dist.ini configuration:
149 [MakeMaker::Custom]
151 eumm_version = 0 ; AutoPrereqs gets actual version from Makefile.PL
152 [FileFinder::ByName / :MakefilePL]
154 file = Makefile.PL
155 [AutoPrereqs]
157 :version = 4.300005 ; need configure_finder
158 configure_finder = :MakefilePL
159 ; Add next line if your Makefile.PL uses modules you ship in inc/
160 configure_finder = :IncModules
161 Then in your Makefile.PL you'd say:
163 use ExtUtils::MakeMaker 6.32; # or whatever version you need
165
167 get_default
168 $plugin->get_default(qw(key1 key2 ...))
169 A template can call this method to extract the specified key(s) from
171 the default WriteMakefile arguments created by the normal MakeMaker
172 plugin and have them formatted into a comma-separated list suitable for
173 a hash constructor or a function's parameter list.
174 If any key has no value (or its value is an empty hash or array ref) it
176 will be omitted from the list. If all keys are omitted, the empty
177 string is returned. Otherwise, the result always ends with a comma.
178 get_prereqs
180 $plugin->get_prereqs($api_version);
181 This is mostly equivalent to
183 $plugin->get_default(qw(BUILD_REQUIRES CONFIGURE_REQUIRES PREREQ_PM
185 TEST_REQUIRES))
186 In other words, it returns all the keys that describe the
188 distribution's prerequisites. The $api_version indicates what keys the
189 template can handle. The currently defined values are:
190 0 (or undef) - Fold TEST_REQUIRES into BUILD_REQUIRES. This provides
192 backwards compatibility with older versions of this plugin and
193 Dist::Zilla.
194 1 - Return TEST_REQUIRES (introduced in ExtUtils::MakeMaker 6.63_03) as
195 a separate key (assuming it's not empty), which requires Dist::Zilla
196 4.300032 or later. Your Makefile.PL should either require
197 ExtUtils::MakeMaker 6.63_03, or fold TEST_REQUIRES into BUILD_REQUIRES
198 if an older version is used (as shown in the SYNOPSIS).
199
201 The ModuleBuild::Custom plugin does basically the same thing as this
202 plugin, but for Build.PL (if you prefer Module::Build).
203 The MakeMaker::Awesome plugin allows you to do similar things to your
205 Makefile.PL, but it works in a very different way. With
206 MakeMaker::Awesome, you subclass the plugin and override the methods
207 that generate Makefile.PL. In my opinion, MakeMaker::Awesome has two
208 disadvantages: it's unnecessarily complex, and it doesn't allow you to
209 build your module without doing "dzil build". The only advantage of
210 MakeMaker::Awesome that I can see is that if you had several dists with
211 very similar Makefile.PLs, you could write one subclass of
212 MakeMaker::Awesome and use it in each dist.
213
215 MakeMaker::Custom requires Dist::Zilla (6 or later) and Text::Template.
216 I also recommend applying Template_strict.patch to Text::Template.
217 This will add support for the STRICT option, which will help catch
218 errors in your templates.
219
221 You must not use this in conjunction with the MakeMaker or
222 MakeMaker::Awesome plugins.
223
225 No bugs have been reported.
226
228 Christopher J. Madsen "<perl AT cjmweb.net>"
229 Please report any bugs or feature requests to
231 "<bug-Dist-Zilla-Plugins-CJM AT rt.cpan.org>" or through the web
232 interface at
233 <http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugins-CJM>.
234 You can follow or contribute to Dist-Zilla-Plugins-CJM's development at
236 <https://github.com/madsen/dist-zilla-plugins-cjm>.
237
239 This software is copyright (c) 2017 by Christopher J. Madsen.
240 This is free software; you can redistribute it and/or modify it under
242 the same terms as the Perl 5 programming language system itself.
243
245 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
246 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
247 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
248 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
249 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
250 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
251 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
252 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
253 NECESSARY SERVICING, REPAIR, OR CORRECTION.
254 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
256 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
257 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE
258 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
259 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
260 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
261 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
262 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
263 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
264 DAMAGES.
265perl v5.28.0 2017D-i1s2t-:1:8Zilla::Plugin::MakeMaker::Custom(3)