.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Module::Package 3pm"
.TH Module::Package 3pm "2021-01-08" "perl v5.32.0" "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 "SYNOPSIS"
.IX Header "SYNOPSIS"
In your \f(CW\*(C`Makefile.PL\*(C'\fR:
.PP
.Vb 1
\&    use inc::Module::Package;
.Ve
.PP
or one of these invocations:
.PP
.Vb 3
\&    # These two are functionally the same as above:
\&    use inc::Module::Package \*(Aq:basic\*(Aq;
\&    use inc::Module::Package \*(AqPlugin:basic\*(Aq;
\&
\&    # With Module::Package::Catalyst plugin options
\&    use inc::Module::Package \*(AqCatalyst\*(Aq;
\&
\&    # With Module::Package::Catalyst::common inline plugin class
\&    use inc::Module::Package \*(AqCatalyst:common\*(Aq;
\&
\&    # Pass options to the Module::Package::Ingy::modern constructor
\&    use inc::Module::Package \*(AqIngy:modern\*(Aq,
\&        option1 => \*(Aqvalue1\*(Aq,
\&        option2 => \*(Aqvalue2\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a dropin replacement for Module::Install. It does everything
Module::Install does, but just a bit better.
.PP
Actually this module is simply a wrapper around Module::Install. It attempts
to drastically reduce what goes in a Makefile.PL, while at the same time,
fixing many of the problems that people have had with Module::Install (and
other module frameworks) over the years.
.SH "PROPAGANDA"
.IX Header "PROPAGANDA"
Module::Install took Makefile.PL authoring from a black art to a small set of
powerful and reusable instructions. It allowed packaging gurus to take their
fancy tricks and make them into one liners for the rest of us.
.PP
As the number of plugins has grown over the years, using Module::Install has
itself become a bit of a black art. It's become hard to know all the latest
tricks, put them in the correct order, and make sure you always use the
correct sets for your various Perl modules.
.PP
Added to this is the fact that there are a few problems in Module::Install
design and general usage that are hard to fix and deploy with certainty that
it will work in all cases.
.PP
This is where Module::Package steps in. Module::Package is the next logical
step in Makefile.PL authoring. It allows gurus to create well tested sets of
Module::Install directives, and lets the rest of us use Makefile.PLs that are
one line long. For example:
.PP
.Vb 1
\&    use inc::Module::Package \*(AqCatalyst:widget\*(Aq;
.Ve
.PP
could be the one line Makefile.PL for a Catalyst widget (whatever that is)
module distribution. Assuming someone creates a module called
Module::Package::Catalyst, with an inline class called
Module::Package::Catalyst::widget that inherited from
Module::Package::Plugin.
.PP
Module::Package is pragmatic. Even though you can do everything in one line,
you are still able to make any Module::Install calls as usual. Also you can
pass parameters to the Module::Package plugin.
.PP
.Vb 3
\&    use inc::Module::Package \*(AqCatalyst:widget\*(Aq,
\&        deps_list => 0,
\&        some_cataylst_thing => \*(Aq...\*(Aq;
\&
\&    # All Module::Install plugins still work!
\&    requires \*(AqSome::Module\*(Aq => 3.14;
.Ve
.PP
This allows Module::Package::Catalyst to be configurable, even on the
properties like \f(CW\*(C`deps_list\*(C'\fR that are inherited from
Module::Package::Plugin.
.PP
The point here is that with Module::Package, module packaging just got a whole
lot more powerful and simple. A rare combination!
.SH "FEATURES"
.IX Header "FEATURES"
Module::Package has many advantages over vanilla Module::Install.
.SS "Smaller Makefile.PL Files"
.IX Subsection "Smaller Makefile.PL Files"
In the majority of cases you can reduce your Makefile.PL to a single command.
The core Module::Package invokes the Module::Install plugins that it thinks
you want. You can also name the Module::Package plugin that does exactly the
plugins you want.
.SS "Reduces Module::Install Bloat"
.IX Subsection "Reduces Module::Install Bloat"
Somewhere Module::Install development went awry, and allowed modules that only
have useful code for an author, to be bundled into a distribution. Over time,
this has created a lot of wasted space on \s-1CPAN\s0 mirrors. Module::Package fixes
this.
.SS "Collaborator Plugin Discovery"
.IX Subsection "Collaborator Plugin Discovery"
An increasing problem with Module::Install is that when people check out your
module source from a repository, they don't know which Module::Install plugin
modules you have used. That's because the Makefile.PL only requires the
function names, not the module names that they come from.
.PP
Many people have realized this problem, and worked around it in various
suboptimal ways. Module::Package manages this problem for you.
.SS "Feature Grouping and Reuse"
.IX Subsection "Feature Grouping and Reuse"
Module::Install has lots of plugins. Although it is possible with plain
Module::Install, nobody seems to make plugins that group other plugins. This
also might introduce subtle problems of using groups with other groups.
.PP
Module::Package has object oriented plugins whose main purpose is to create
these groups. They inherit base functionality, subclass it to their design
goals and can define options for the user to tweak how they will operate.
.SH "USAGE"
.IX Header "USAGE"
The basic anatomy of a Makefile.PL call to Module::Package is:
.PP
.Vb 2
\&    use inc::Module::Package \*(AqPluginName:flavor <version>\*(Aq,
\&        $option1 => $value1;
.Ve
.PP
The \f(CW\*(C`inc::Module::Package\*(C'\fR part uses the Module::Install \f(CW\*(C`inc\*(C'\fR bootstrapping
trick.
.PP
\&\f(CW\*(C`PluginName:flavor\*(C'\fR (note the single ':') resolves to the inline class
\&\f(CW\*(C`Module::Package::PluginName::flavor\*(C'\fR, within the module
\&\f(CW\*(C`Module::Package::PluginName\*(C'\fR. Module::Package::PluginName::flavor must be a
subclass of Module::Package::Plugin.
.PP
An optional version can be used after the plugin name.
.PP
Optional key/value pairs can follow the Plugin specification. They are used to
pass information to the plugin. See Plugin docs for more details.
.PP
If \f(CW\*(C`:flavor\*(C'\fR is omitted, the class Module::Package::PluginName is
used. The idea is that you can create a single module with many different
plugin styles.
.PP
If \f(CW\*(C`PluginName\*(C'\fR is omitted, then \f(CW\*(C`:flavor\*(C'\fR is used against
Module::Package::Plugin. These are a set of common plugin classes that you
can use.
.PP
If \f(CW\*(C`PluginName:flavor\*(C'\fR is omitted altogether, it is the same as saying
\&'Plugin:basic'. Note that you need to specify the ':basic' plugin if you want
to also pass it options.
.SH "STATUS"
.IX Header "STATUS"
This is still an early release. We are still shaking out the bugs. You might
want to hold off for a bit longer before using Module::Package for important
modules.