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