NAME
    Dist::Zilla::Plugin::MakeMaker::Awesome - A more awesome MakeMaker
    plugin for Dist::Zilla

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% compatable with Dist::Zilla::Plugin::MakeMaker, but
    if you need something more complex you can just subclass it:

    Simple use, in your dist.ini:

        ;; Replace [MakeMaker]
        ;[MakeMaker]
        [MakeMaker::Awesome]

    More complex use, 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:

        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:

        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:

        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 Makefile.PL that Dist::Zilla can't
    replace via its default facilities you'll be able replace it by using
    this module.

OVERRIDE
    These are the methods you can currently override in your custom inc/
    module. The work that this module does is entirely done in small modular
    methods that can be overriden in your subclass. Here are some of the
    highlights:

  _build_MakeFile_PL_template
    Returns Text::Template string used to construct the Makefile.PL.

  _build_WriteMakefile_args
    A "HashRef" of arguments that'll be passed to ExtUtils::MakeMaker's
    "WriteMakefile" function.

  _build_WriteMakefile_dump
    Takes the return value of "_build_WriteMakefile_args" and constructs a
    Str that'll be included in the Makefile.PL by
    "_build_MakeFile_PL_template".

  test_dirs
  bin_dirs
  share_dirs
  exe_files
    The test/bin/share dirs and exe_files. These'll all be passed to
    /"_build_WriteMakefile_args" later.

  dir_plugins
    Used for Dist::Zilla::Plugin::ShareDir support. Don't touch it if you
    don't need some deep ShareDir magic.

  _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.

BUGS
    This plugin would suck less if Dist::Zilla didn't use a INI-based config
    system so you could add a 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".

AUTHOR
    Ævar Arnfjörð Bjarmason <avar@cpan.org>

LICENSE AND COPYRIGHT
    Copyright 2010 Ævar Arnfjörð Bjarmason <avar@cpan.org>

    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.