.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Dist::Zilla::Plugin::MakeMaker::Awesome 3pm" .TH Dist::Zilla::Plugin::MakeMaker::Awesome 3pm "2019-07-16" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dist::Zilla::Plugin::MakeMaker::Awesome \- A more awesome MakeMaker plugin for Dist::Zilla .SH "VERSION" .IX Header "VERSION" version 0.48 .SH "SYNOPSIS" .IX Header "SYNOPSIS" In your \fIdist.ini\fR: .PP .Vb 10 \& [MakeMaker::Awesome] \& WriteMakefile_arg = CCFLAGS => \`pkg\-config \-\-cflags libpng\` \& WriteMakefile_arg = LIBS => [ \`pkg\-config \-\-libs libpng\` ] \& header = die \*(AqUnsupported OS\*(Aq if $^O eq \*(AqMSWin32\*(Aq; \& delimiter = | \& footer = |package MY; \& footer = |sub postamble { \& footer = | my $self = shift; \& footer = | return $self\->SUPER::postamble . "\en\enfoo: bar\en\et$(CP) bar foo\en"; \& footer = |} .Ve .PP or: .PP .Vb 3 \& ;; Replace [MakeMaker] \& ;[MakeMaker] \& [=inc::MyMakeMaker] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Dist::Zilla's MakeMaker plugin is limited, if you want to stray from the marked path and do something that would normally be done in a \f(CW\*(C`package MY\*(C'\fR section or otherwise run custom code in your \fIMakefile.PL\fR you're out of luck. .PP This plugin is 100% compatible with Dist::Zilla::Plugin::MakeMaker \*(-- we add additional customization hooks by subclassing it. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" Many features can be accessed directly via \fIdist.ini\fR, by setting options. For options where you expect a multi-line string to be inserted into \&\fIMakefile.PL\fR, use the config option more than once, setting each line separately. .SS "WriteMakefile_arg" .IX Subsection "WriteMakefile_arg" A string, which evaluates to an even-numbered list, which will be included in the call to \&\f(CW\*(C`WriteMakefile\*(C'\fR. Any code is legal that can be inserted into a list of other key-value pairs, for example: .PP .Vb 2 \& [MakeMaker::Awesome] \& WriteMakefile_arg = ( $^O eq \*(Aqsolaris\*(Aq ? ( CCFLAGS => \*(Aq\-Wall\*(Aq ) : ()) .Ve .PP Can be used more than once. Available since version 0.21. .PP Note: you (intentionally) cannot use this mechanism for specifying dynamic prerequisites, as previous occurrences of a top-level key will be overwritten (additionally, you cannot set the fallback prereqs from here). You should take a look at [DynamicPrereqs] for this. .SS "header" .IX Subsection "header" A line of code which is included near the top of \fIMakefile.PL\fR. Can be used more than once. Available since version 0.26. .SS "header_file" .IX Subsection "header_file" The name of a file in the source tree (does not need to be gathered in the build) whose content is inserted near the top of \fIMakefile.PL\fR. Available since version 0.35. .SS "footer" .IX Subsection "footer" A line of code which is included at the bottom of \fIMakefile.PL\fR. Can be used more than once. Available since version 0.26. .SS "footer_file" .IX Subsection "footer_file" The name of a file in the source tree (does not need to be gathered in the build) whose content is inserted at the bottom of \fIMakefile.PL\fR. Available since version 0.35. .SS "delimiter" .IX Subsection "delimiter" A string, usually a single character, which is stripped from the beginning of all \f(CW\*(C`WriteMakefile_arg\*(C'\fR, \f(CW\*(C`header\*(C'\fR, and \f(CW\*(C`footer\*(C'\fR lines. This is because the \&\s-1INI\s0 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. This is crucial for the formatting of \fIMakefile\fRs, but a nice thing to have when inserting any block of code. .PP Available since version 0.27. .SS "test_file" .IX Subsection "test_file" A glob path given to the \f(CW\*(C`test => { TESTS => ... }\*(C'\fR parameter for \&\*(L"WriteMakefile\*(R" in ExtUtils::MakeMaker. Can be used more than once. Defaults to \fI.t\fR files under \fIt/\fR. \fB\s-1NOT\s0\fR a directory name, despite the name. .PP Available since version 0.21. .SS "exe_file" .IX Subsection "exe_file" The file given to the \f(CW\*(C`EXE_FILES\*(C'\fR parameter for \&\*(L"WriteMakefile\*(R" in ExtUtils::MakeMaker. Can be used more than once. Defaults to using data from \f(CW\*(C`:ExecDir\*(C'\fR plugins. .PP Available since version 0.21. .SH "SUBCLASSING" .IX Header "SUBCLASSING" You can further customize the content of \fIMakefile.PL\fR by subclassing this plugin, Dist::Zilla::Plugin::MakeMaker::Awesome. .PP As an example, adding a \f(CW\*(C`package MY\*(C'\fR section to your \&\fIMakefile.PL\fR: .PP In your \fIdist.ini\fR: .PP .Vb 1 \& [=inc::MyDistMakeMaker / MyDistMakeMaker] .Ve .PP Then in your \fIinc/MyDistMakeMaker.pm\fR, real example from Hailo (which has \f(CW\*(C`[=inc::HailoMakeMaker / HailoMakeMaker]\*(C'\fR in its \&\fIdist.ini\fR): .PP .Vb 2 \& package inc::HailoMakeMaker; \& use Moose; \& \& extends \*(AqDist::Zilla::Plugin::MakeMaker::Awesome\*(Aq; \& \& override _build_MakeFile_PL_template => sub { \& my ($self) = @_; \& my $template = super(); \& \& $template .= <<\*(AqTEMPLATE\*(Aq; \& package MY; \& \& sub test { \& my $inherited = shift\->SUPER::test(@_); \& \& # Run tests with Moose and Mouse \& $inherited =~ s/^test_dynamic :: pure_all\en\et(.*?)\en/test_dynamic :: pure_all\en\etANY_MOOSE=Mouse $1\en\etANY_MOOSE=Moose $1\en/m; \& \& return $inherited; \& } \& TEMPLATE \& \& return $template; \& }; \& \& _\|_PACKAGE_\|_\->meta\->make_immutable; .Ve .PP Or maybe you're writing an \s-1XS\s0 distro and want to pass custom arguments to \f(CW\*(C`WriteMakefile()\*(C'\fR, here's an example of adding a \f(CW\*(C`LIBS\*(C'\fR argument in re::engine::PCRE (note that you can also achieve this without subclassing, by passing the \*(L"WriteMakefile_arg\*(R" option): .PP .Vb 2 \& package inc::PCREMakeMaker; \& use Moose; \& \& extends \*(AqDist::Zilla::Plugin::MakeMaker::Awesome\*(Aq; \& \& override _build_WriteMakefile_args => sub { +{ \& # Add LIBS => to WriteMakefile() args \& %{ super() }, \& LIBS => [ \*(Aq\-lpcre\*(Aq ], \& } }; \& \& _\|_PACKAGE_\|_\->meta\->make_immutable; .Ve .PP And another example from re::engine::Plan9, which determines the arguments dynamically at build time: .PP .Vb 2 \& package inc::Plan9MakeMaker; \& use Moose; \& \& extends \*(AqDist::Zilla::Plugin::MakeMaker::Awesome\*(Aq; \& \& override _build_WriteMakefile_args => sub { \& my ($self) = @_; \& \& our @DIR = qw(libutf libfmt libregexp); \& our @OBJ = map { s/\e.c$/.o/; $_ } \& grep { ! /test/ } \& glob "lib*/*.c"; \& \& return +{ \& %{ super() }, \& DIR => [ @DIR ], \& INC => join(\*(Aq \*(Aq, map "\-I$_", @DIR), \& \& # This used to be \*(Aq\-shared lib*/*.o\*(Aq but that doesn\*(Aqt work on Win32 \& LDDLFLAGS => "\-shared @OBJ", \& }; \& }; \& \& _\|_PACKAGE_\|_\->meta\->make_immutable; .Ve .PP If you have custom code in your ExtUtils::MakeMaker\-based \&\fIMakefile.PL\fR that Dist::Zilla can't replace via its default facilities you'll be able to replace it by using this module. .PP Even if your \fIMakefile.PL\fR isn't ExtUtils::MakeMaker\-based you should be able to override it. You'll just have to provide a new \&\*(L"_build_MakeFile_PL_template\*(R". .SS "\s-1OVERRIDABLE METHODS\s0" .IX Subsection "OVERRIDABLE METHODS" These are the methods you can currently \f(CW\*(C`override\*(C'\fR or method-modify in your custom \fIinc/\fR module. The work that this module does is entirely done in small modular methods that can be overridden in your subclass. Here are some of the highlights: .PP \fI_build_MakeFile_PL_template\fR .IX Subsection "_build_MakeFile_PL_template" .PP Returns a Text::Template string used to construct the \fIMakefile.PL\fR. .PP If you need to insert some additional code to the beginning or end of \&\fIMakefile.PL\fR (without modifying the existing content, you should use an \&\f(CW\*(C`around\*(C'\fR method modifier, something like this: .PP .Vb 3 \& around _build_MakeFile_PL_template => sub { \& my $orig = shift; \& my $self = shift; \& \& my $NEW_CONTENT = ...; \& \& # insert new content near the beginning of the file, preserving the \& # existing header content \& my $string = $self\->$orig(@_); \& $string =~ m/use warnings;\en\en/g; \& return substr($string, 0, pos($string)) . $NEW_CONTENT . substr($string, pos($string)); \& }; .Ve .PP \fI_build_WriteMakefile_args\fR .IX Subsection "_build_WriteMakefile_args" .PP A \f(CW\*(C`HashRef\*(C'\fR of arguments that will be passed to ExtUtils::MakeMaker's \f(CW\*(C`WriteMakefile\*(C'\fR function. .PP \fI_build_WriteMakefile_dump\fR .IX Subsection "_build_WriteMakefile_dump" .PP Takes the return value of \*(L"_build_WriteMakefile_args\*(R" and constructs a Str that will be included in the \fIMakefile.PL\fR by \&\*(L"_build_MakeFile_PL_template\*(R". .PP \fI_build_header\fR .IX Subsection "_build_header" .PP A \f(CW\*(C`Str\*(C'\fR of code that will be included near the top of \fIMakefile.PL\fR. .PP \fI_build_footer\fR .IX Subsection "_build_footer" .PP A \f(CW\*(C`Str\*(C'\fR of code that will be included at the bottom of \fIMakefile.PL\fR. .PP \fI_build_test_files\fR .IX Subsection "_build_test_files" .PP The glob paths given to the \f(CW\*(C`test => { TESTS => ... }\*(C'\fR parameter for \&\*(L"WriteMakefile\*(R" in ExtUtils::MakeMaker. Defaults to \fI.t\fR files under \fIt/\fR. \&\fB\s-1NOT\s0\fR directories, despite the name. .PP \fI_build_exe_files\fR .IX Subsection "_build_exe_files" .PP The files given to the \f(CW\*(C`EXE_FILES\*(C'\fR parameter for \&\*(L"WriteMakefile\*(R" in ExtUtils::MakeMaker. Defaults to using data from \f(CW\*(C`:ExecDir\*(C'\fR plugins. .PP \fI_build_min_perl_version\fR .IX Subsection "_build_min_perl_version" .PP Extracts from the distribution prerequisite object the minimum version of perl required; used for the \f(CW\*(C`MIN_PERL_VERSION\*(C'\fR parameter for \&\*(L"WriteMakefile\*(R" in ExtUtils::MakeMaker. .PP \fIregister_prereqs\fR .IX Subsection "register_prereqs" .PP \fIgather_files\fR .IX Subsection "gather_files" .PP \fIsetup_installer\fR .IX Subsection "setup_installer" .PP The test/bin/share dirs and exe_files. These will all be passed to \&\fI/\*(L"_build_WriteMakefile_args\*(R"\fR later. .PP \fI_build_share_dir_block\fR .IX Subsection "_build_share_dir_block" .PP An \f(CW\*(C`ArrayRef[Str]\*(C'\fR with two elements to be used by \&\*(L"_build_MakeFile_PL_template\*(R". The first will declare your sharedir and the second will add a magic \&\f(CW\*(C`package MY\*(C'\fR section to install it. Deep magic. .SS "\s-1OTHER\s0" .IX Subsection "OTHER" The main entry point is \f(CW\*(C`setup_installer\*(C'\fR via the Dist::Zilla::Role::InstallTool role. There are also other magic Dist::Zilla roles, check the source for more info. .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .IP "attempt to add \fIMakefile.PL\fR multiple times" 4 .IX Item "attempt to add Makefile.PL multiple times" This error from Dist::Zilla means that you've used both \&\f(CW\*(C`[MakeMaker]\*(C'\fR and \f(CW\*(C`[MakeMaker::Awesome]\*(C'\fR. You've either included \&\f(CW\*(C`MakeMaker\*(C'\fR directly in \fIdist.ini\fR, or you have plugin bundle that includes it. See \f(CW@Filter\fR for how to filter it out. .SH "LIMITATIONS" .IX Header "LIMITATIONS" This plugin would suck less if Dist::Zilla didn't use a INI-based config system so you could add stuff like this in your main configuration file like you can with Module::Install. .PP The \fI.ini\fR file format can only support key-value pairs whereas any complex use of ExtUtils::MakeMaker requires running custom Perl code and passing complex data structures to \f(CW\*(C`WriteMakefile\*(C'\fR. .SH "AFTERWORD" .IX Header "AFTERWORD" .Vb 10 \& _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ \& < everything is AWESOME! > \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \e _\|_\|_\-\-\-\-\-\-\-_\|_\|_ \& \e _\-~~ ~~\-_ \& \e _\-~ /~\-_ \& /^\e_\|_/^\e /~ \e / \e \& /| O|| O| / \e_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_/ \e \& | |_\|_\|_||_\|_| / / \e \e \& | \e / / \e \e \& | (_\|_\|_\|_\|_\|_\|_) /_\|_\|_\|_\|_\|_/ \e_\|_\|_\|_\|_\|_\|_\|_\|_ \e \& | / / \e / \e \& \e \e^\e\e \e / \e / \& \e || \e_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_/ _\-_ //\e_\|_// \& \e ||\-\-\-\-\-\-_\-~~\-_ \-\-\-\-\-\-\-\-\-\-\-\-\- \e \-\-/~ ~\e || _\|_/ \& ~\-\-\-\-\-||====/~ |==================| |/~~~~~ \& (_(_\|_/ ./ / \e_\e \e. \& (_(_\|_\|_/ \e_\|_\|_\|_\|_)_) .Ve .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-Dist\-Zilla\-Plugin\-MakeMaker\-Awesome@rt.cpan.org ). .PP There is also a mailing list available for users of this distribution, at . .PP There is also an irc channel available for users of this distribution, at \&\f(CW\*(C`#distzilla\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR . .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 \&\*(Aevar Arnfjo\*:r\*(d- Bjarmason .IP "\(bu" 4 Karen Etheridge .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Jesse Luehrs .IP "\(bu" 4 Robin Smidsro\*/d .IP "\(bu" 4 Tabulo .IP "\(bu" 4 Vladimir Timofeev .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2010 by \*(Aevar Arnfjo\*:r\*(d- Bjarmason. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.