Dist::...Awesome(3pm)

📦 version 0.49, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Dist::Zilla::Plugin::MakeMaker::Awesome(3pm) 💖

okay bestie, part 1 of the manual page for Dist::Zilla::Plugin::MakeMaker::Awesome — and it's literally the "more awesome MakeMaker plugin for Dist::Zilla". Buckle up. 🎀

✨ NAME ✨

Dist::Zilla::Plugin::MakeMaker::Awesome — A more awesome MakeMaker plugin for Dist::Zilla

🌈 VERSION 🌈

version 0.49

🎀 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\n" 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 🦋

So Dist::Zilla's regular MakeMaker plugin is a little limited. If you wanna stray off the marked path and do something that would normally live in a package MY section, or run custom code in your Makefile.PL? Yeah, you're out of luck with the vanilla one. 😭

This plugin is 100% compatible with Dist::Zilla::Plugin::MakeMaker — we just add extra customization hooks by subclassing it. Periodt. 💅

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

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.

🌟 template_arguments 🌟

Returns a hashref of arguments to be used by the template returned by Makefile_PL_template. Normally you would around (see "Around modifiers" in Moose::Manual::Method::Modifiers) this method to add on any additional template variables you need.

🌟 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 ✨

Okay bestie, the docs are done and the vibes are immaculate, so here's your reward 🎀

            ________________________
           < everything is AWESOME! >
            ------------------------
               \                                  ___-------___
                \                             _-~~             ~~-_
                 \                         _-~                    /~-_
                        /^\__/^\         /~  \                   /    \
                      /|  O|| O|        /      \_______________/        \
                     | |___||__|      /       /                \          \
                     |          \    /      /                    \          \
                     |   (_______) /______/                        \_________ \
                     |         / /         \                      /            \
                      \         \^\\         \                  /               \     /
                        \         ||           \______________/      _-_       //\__//
                          \       ||------_-~~-_ ------------- \ --/~   ~\    || __/
                            ~-----||====/~     |==================|       |/~~~~~
                             (_(__/  ./     /                    \_\      \.
                                    (_(___/                         \_____)_)

No notes. She said what she said. 🐄💖

🫶 SUPPORT 🫶

Found a bug? Girl, tell someone, don't suffer in silence 😭

There's a mailing list for users of this distribution too, right here: http://dzil.org/#mailing-list

And if you wanna just chat about it, there's an irc channel for users of this distribution — it's #distzilla on irc.perl.org (irc://irc.perl.org/#distzilla). Come hang out, it's giving community 🦋

👑 AUTHORS 👑

The literal legends who made this happen:

  • **AEvar Arnfjoer` Bjarmason** — avar@cpan.org
  • Karen Etheridge — ether@cpan.org

🌸 CONTRIBUTORS 🌸

And the besties who pulled up and helped 💅

  • Jesse Luehrs — doy@tozt.net
  • Robin Smidsrod — robin@smidsrod.no
  • Tabulo — dev@tabulo.net
  • Vladimir Timofeev — vovkasm@gmail.com

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.

So like… yes you can remix it, yes you can share it, just keep it under the same terms as Perl 5 itself. That's the deal, and honestly? Iconic behaviour. 🌈

And that's the whole page, bestie, we made it to the end together 🥹 This was Dist::...Awesome(3pm), generated from perl v5.32.1, dated 2021-09-30 — so if you're reading this in the future, hi, hope you're slaying. Go forth and be awesome, everything is AWESOME, periodt. 💖✨

📦 where this page comes from