1Dist::Zilla::Plugin::MaUkseeMrakCeorn:t:rCiubsuttoemdD(i3Ps)etr:l:ZDiolcluam:e:nPtlautgiionn::MakeMaker::Custom(3)
2
3
4

NAME

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

VERSION

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

SYNOPSIS

15       In dist.ini:
16
17         [MakeMaker::Custom]
18         eumm_version = 0.34  ; the default comes from the MakeMaker plugin
19
20       In your Makefile.PL:
21
22         use ExtUtils::MakeMaker;
23
24         ##{ $share_dir_code{preamble} || '' ##}
25
26         my %args = (
27           NAME => "My::Module",
28         ##{ $plugin->get_default(qw(ABSTRACT AUTHOR LICENSE VERSION)) ##}
29         ##{ $plugin->get_prereqs(1) ##}
30         );
31
32         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
45         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
58         delete $args{CONFIGURE_REQUIRES}
59           unless eval { ExtUtils::MakeMaker->VERSION(6.52) };
60
61         delete $args{LICENSE}
62           unless eval { ExtUtils::MakeMaker->VERSION(6.31) };
63
64         WriteMakefile(%args);
65
66         ##{ $share_dir_code{postamble} || '' ##}
67
68       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
74       And if you're not adding your own code to Makefile.PL, you don't need
75       this plugin.
76

DESCRIPTION

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
82       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
86       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
93       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
97       The template may use the following variables:
98
99       %default_args
100           The hash of arguments for WriteMakefile generated by the normal
101           MakeMaker plugin.
102
103       $dist
104           The name of the distribution.
105
106       $eumm_version
107           The minimum version of ExtUtils::MakeMaker required (from the
108           "eumm_version" attribute of this plugin).
109
110       %meta
111           The hash of metadata (in META 2 format) that will be stored in
112           META.json.
113
114       $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
119       $plugin
120           The MakeMaker::Custom object that is processing the template.
121
122       %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
131           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
135       $version
136           The distribution's version number.
137
138       $zilla
139           The Dist::Zilla object that is creating the distribution.
140
141   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
148       Example dist.ini configuration:
149
150         [MakeMaker::Custom]
151         eumm_version = 0 ; AutoPrereqs gets actual version from Makefile.PL
152
153         [FileFinder::ByName / :MakefilePL]
154         file = Makefile.PL
155
156         [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
162       Then in your Makefile.PL you'd say:
163
164         use ExtUtils::MakeMaker 6.32; # or whatever version you need
165

METHODS

167   get_default
168         $plugin->get_default(qw(key1 key2 ...))
169
170       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
175       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
179   get_prereqs
180         $plugin->get_prereqs($api_version);
181
182       This is mostly equivalent to
183
184         $plugin->get_default(qw(BUILD_REQUIRES CONFIGURE_REQUIRES PREREQ_PM
185                                 TEST_REQUIRES))
186
187       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
191       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

SEE ALSO

201       The ModuleBuild::Custom plugin does basically the same thing as this
202       plugin, but for Build.PL (if you prefer Module::Build).
203
204       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

DEPENDENCIES

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

INCOMPATIBILITIES

221       You must not use this in conjunction with the MakeMaker or
222       MakeMaker::Awesome plugins.
223

BUGS AND LIMITATIONS

225       No bugs have been reported.
226

AUTHOR

228       Christopher J. Madsen  "<perl AT cjmweb.net>"
229
230       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
235       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
241       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

DISCLAIMER OF WARRANTY

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
255       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.
265
266
267
268perl v5.28.1                      2017D-i1s2t-:1:8Zilla::Plugin::MakeMaker::Custom(3)
Impressum