Provided by: libdist-zilla-plugin-makemaker-awesome-perl_0.39-1_all 
NAME
Dist::Zilla::Plugin::MakeMaker::Awesome - A more awesome MakeMaker plugin for Dist::Zilla
VERSION
version 0.39
SYNOPSIS
In your dist.ini:
[MakeMaker::Awesome]
WriteMakefile_arg = CCFLAGS => `pkg-config --cflags libpng`
WriteMakefile_arg = LIBS => [ `pkg-config --libs libpng` ]
header = die 'Unsupported OS' if $^O eq 'MSWin32';
delimiter = |
footer = |package MY;
footer = |sub postamble {
footer = | my $self = shift;
footer = | return $self->SUPER::postamble . "\n\nfoo: bar\n\t$(CP) bar foo\n";
footer = |}
or:
;; Replace [MakeMaker]
;[MakeMaker]
[=inc::MyMakeMaker]
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 "package MY" section or otherwise run custom
code in your Makefile.PL you're out of luck.
This plugin is 100% compatible with Dist::Zilla::Plugin::MakeMaker -- we add additional
customization hooks by subclassing it.
CONFIGURATION OPTIONS
Many features can be accessed directly via dist.ini, by setting options. For options
where you expect a multi-line string to be inserted into Makefile.PL, use the config
option more than once, setting each line separately.
WriteMakefile_arg
A string, which evaluates to an even-numbered list, which will be included in the call to
"WriteMakefile". Any code is legal that can be inserted into a list of other key-value
pairs, for example:
[MakeMaker::Awesome]
WriteMakefile_arg = ( $^O eq 'solaris' ? ( CCFLAGS => '-Wall' ) : ())
Can be used more than once. Available since version 0.21.
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.
header
A line of code which is included near the top of Makefile.PL. Can be used more than once.
Available since version 0.26.
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 Makefile.PL. Available since version 0.35.
footer
A line of code which is included at the bottom of Makefile.PL. Can be used more than
once. Available since version 0.26.
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 Makefile.PL. Available since version 0.35.
delimiter
A string, usually a single character, which is stripped from the beginning of all
"WriteMakefile_arg", "header", and "footer" 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. This is crucial for the
formatting of Makefiles, but a nice thing to have when inserting any block of code.
Available since version 0.27.
test_file
A glob path given to the "test => { TESTS => ... }" parameter for "WriteMakefile" in
ExtUtils::MakeMaker. Can be used more than once. Defaults to .t files under t/. NOT a
directory name, despite the name.
Available since version 0.21.
exe_file
The file given to the "EXE_FILES" parameter for "WriteMakefile" in ExtUtils::MakeMaker.
Can be used more than once. Defaults to using data from ":ExecDir" plugins.
Available since version 0.21.
SUBCLASSING
You can further customize the content of Makefile.PL by subclassing this plugin,
Dist::Zilla::Plugin::MakeMaker::Awesome.
As an example, adding a "package MY" section to your Makefile.PL:
In your dist.ini:
[=inc::MyDistMakeMaker / MyDistMakeMaker]
Then in your inc/MyDistMakeMaker.pm, real example from Hailo (which has
"[=inc::HailoMakeMaker / HailoMakeMaker]" in its dist.ini):
package inc::HailoMakeMaker;
use Moose;
extends 'Dist::Zilla::Plugin::MakeMaker::Awesome';
override _build_MakeFile_PL_template => sub {
my ($self) = @_;
my $template = super();
$template .= <<'TEMPLATE';
package MY;
sub test {
my $inherited = shift->SUPER::test(@_);
# Run tests with Moose and Mouse
$inherited =~ s/^test_dynamic :: pure_all\n\t(.*?)\n/test_dynamic :: pure_all\n\tANY_MOOSE=Mouse $1\n\tANY_MOOSE=Moose $1\n/m;
return $inherited;
}
TEMPLATE
return $template;
};
__PACKAGE__->meta->make_immutable;
Or maybe you're writing an XS distro and want to pass custom arguments to
"WriteMakefile()", here's an example of adding a "LIBS" argument in re::engine::PCRE (note
that you can also achieve this without subclassing, by passing the "WriteMakefile_arg"
option):
package inc::PCREMakeMaker;
use Moose;
extends 'Dist::Zilla::Plugin::MakeMaker::Awesome';
override _build_WriteMakefile_args => sub { +{
# Add LIBS => to WriteMakefile() args
%{ super() },
LIBS => [ '-lpcre' ],
} };
__PACKAGE__->meta->make_immutable;
And another example from re::engine::Plan9, which determines the arguments dynamically at
build time:
package inc::Plan9MakeMaker;
use Moose;
extends 'Dist::Zilla::Plugin::MakeMaker::Awesome';
override _build_WriteMakefile_args => sub {
my ($self) = @_;
our @DIR = qw(libutf libfmt libregexp);
our @OBJ = map { s/\.c$/.o/; $_ }
grep { ! /test/ }
glob "lib*/*.c";
return +{
%{ super() },
DIR => [ @DIR ],
INC => join(' ', map { "-I$_" } @DIR),
# This used to be '-shared lib*/*.o' but that doesn't work on Win32
LDDLFLAGS => "-shared @OBJ",
};
};
__PACKAGE__->meta->make_immutable;
If you have custom code in your ExtUtils::MakeMaker-based Makefile.PL that Dist::Zilla
can't replace via its default facilities you'll be able to replace it by using this
module.
Even if your Makefile.PL isn't ExtUtils::MakeMaker-based you should be able to override
it. You'll just have to provide a new "_build_MakeFile_PL_template".
OVERRIDABLE METHODS
These are the methods you can currently "override" or method-modify in your custom inc/
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:
_build_MakeFile_PL_template
Returns a Text::Template string used to construct the Makefile.PL.
If you need to insert some additional code to the beginning or end of Makefile.PL (without
modifying the existing content, you should use an "around" method modifier, something like
this:
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;\n\n/g;
return substr($string, 0, pos($string)) . $NEW_CONTENT . substr($string, pos($string));
};
_build_WriteMakefile_args
A "HashRef" of arguments that will be passed to ExtUtils::MakeMaker's "WriteMakefile"
function.
_build_WriteMakefile_dump
Takes the return value of "_build_WriteMakefile_args" and constructs a Str that will be
included in the Makefile.PL by "_build_MakeFile_PL_template".
_build_header
A "Str" of code that will be included near the top of Makefile.PL.
_build_footer
A "Str" of code that will be included at the bottom of Makefile.PL.
_build_test_files
The glob paths given to the "test => { TESTS => ... }" parameter for "WriteMakefile" in
ExtUtils::MakeMaker. Defaults to .t files under t/. NOT directories, despite the name.
_build_exe_files
The files given to the "EXE_FILES" parameter for "WriteMakefile" in ExtUtils::MakeMaker.
Defaults to using data from ":ExecDir" plugins.
_build_min_perl_version
Extracts from the distribution prerequisite object the minimum version of perl required;
used for the "MIN_PERL_VERSION" parameter for "WriteMakefile" in ExtUtils::MakeMaker.
register_prereqs
gather_files
setup_installer
The test/bin/share dirs and exe_files. These will all be passed to
/"_build_WriteMakefile_args" later.
_build_share_dir_block
An "ArrayRef[Str]" with two elements to be used by "_build_MakeFile_PL_template". The
first will declare your sharedir and the second will add a magic "package MY" section to
install it. Deep magic.
OTHER
The main entry point is "setup_installer" via the Dist::Zilla::Role::InstallTool role.
There are also other magic Dist::Zilla roles, check the source for more info.
DIAGNOSTICS
attempt to add Makefile.PL multiple times
This error from Dist::Zilla means that you've used both "[MakeMaker]" and
"[MakeMaker::Awesome]". You've either included "MakeMaker" directly in dist.ini, or
you have plugin bundle that includes it. See @Filter for how to filter it out.
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.
The .ini 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 "WriteMakefile".
AFTERWORD
________________________
< everything is AWESOME! >
------------------------
\ ___-------___
\ _-~~ ~~-_
\ _-~ /~-_
/^\__/^\ /~ \ / \
/| O|| O| / \_______________/ \
| |___||__| / / \ \
| \ / / \ \
| (_______) /______/ \_________ \
| / / \ / \
\ \^\\ \ / \ /
\ || \______________/ _-_ //\__//
\ ||------_-~~-_ ------------- \ --/~ ~\ || __/
~-----||====/~ |==================| |/~~~~~
(_(__/ ./ / \_\ \.
(_(___/ \_____)_)
SUPPORT
Bugs may be submitted through the RT bug tracker
<https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-MakeMaker-Awesome>
(or bug-Dist-Zilla-Plugin-MakeMaker-Awesome@rt.cpan.org <mailto:bug-Dist-Zilla-Plugin-
MakeMaker-Awesome@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>.
AUTHORS
• AEvar Arnfjoer` Bjarmason <avar@cpan.org>
• Karen Etheridge <ether@cpan.org>
CONTRIBUTORS
• Jesse Luehrs <doy@tozt.net>
• Robin Smidsrod <robin@smidsrod.no>
• Vladimir Timofeev <vovkasm@gmail.com>
COPYRIGHT AND LICENCE
This software is copyright (c) 2010 by AEvar Arnfjoer` Bjarmason.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.
perl v5.26.1 2017-11-0Dist::Zilla::Plugin::MakeMaker::Awesome(3pm)