1Module::Package(3)    User Contributed Perl Documentation   Module::Package(3)
2
3
4

SYNOPSIS

6       In your "Makefile.PL":
7
8           use inc::Module::Package;
9
10       or one of these invocations:
11
12           # These two are functionally the same as above:
13           use inc::Module::Package ':basic';
14           use inc::Module::Package 'Plugin:basic';
15
16           # With Module::Package::Catalyst plugin options
17           use inc::Module::Package 'Catalyst';
18
19           # With Module::Package::Catalyst::common inline plugin class
20           use inc::Module::Package 'Catalyst:common';
21
22           # Pass options to the Module::Package::Ingy::modern constructor
23           use inc::Module::Package 'Ingy:modern',
24               option1 => 'value1',
25               option2 => 'value2';
26

DESCRIPTION

28       This module is a dropin replacement for Module::Install. It does
29       everything Module::Install does, but just a bit better.
30
31       Actually this module is simply a wrapper around Module::Install. It
32       attempts to drastically reduce what goes in a Makefile.PL, while at the
33       same time, fixing many of the problems that people have had with
34       Module::Install (and other module frameworks) over the years.
35

PROPAGANDA

37       Module::Install took Makefile.PL authoring from a black art to a small
38       set of powerful and reusable instructions. It allowed packaging gurus
39       to take their fancy tricks and make them into one liners for the rest
40       of us.
41
42       As the number of plugins has grown over the years, using
43       Module::Install has itself become a bit of a black art. It's become
44       hard to know all the latest tricks, put them in the correct order, and
45       make sure you always use the correct sets for your various Perl
46       modules.
47
48       Added to this is the fact that there are a few problems in
49       Module::Install design and general usage that are hard to fix and
50       deploy with certainty that it will work in all cases.
51
52       This is where Module::Package steps in. Module::Package is the next
53       logical step in Makefile.PL authoring. It allows gurus to create well
54       tested sets of Module::Install directives, and lets the rest of us use
55       Makefile.PLs that are one line long. For example:
56
57           use inc::Module::Package 'Catalyst:widget';
58
59       could be the one line Makefile.PL for a Catalyst widget (whatever that
60       is) module distribution. Assuming someone creates a module called
61       Module::Package::Catalyst, with an inline class called
62       Module::Package::Catalyst::widget that inherited from
63       Module::Package::Plugin.
64
65       Module::Package is pragmatic. Even though you can do everything in one
66       line, you are still able to make any Module::Install calls as usual.
67       Also you can pass parameters to the Module::Package plugin.
68
69           use inc::Module::Package 'Catalyst:widget',
70               deps_list => 0,
71               some_cataylst_thing => '...';
72
73           # All Module::Install plugins still work!
74           requires 'Some::Module' => 3.14;
75
76       This allows Module::Package::Catalyst to be configurable, even on the
77       properties like "deps_list" that are inherited from
78       Module::Package::Plugin.
79
80       The point here is that with Module::Package, module packaging just got
81       a whole lot more powerful and simple. A rare combination!
82

FEATURES

84       Module::Package has many advantages over vanilla Module::Install.
85
86   Smaller Makefile.PL Files
87       In the majority of cases you can reduce your Makefile.PL to a single
88       command.  The core Module::Package invokes the Module::Install plugins
89       that it thinks you want. You can also name the Module::Package plugin
90       that does exactly the plugins you want.
91
92   Reduces Module::Install Bloat
93       Somewhere Module::Install development went awry, and allowed modules
94       that only have useful code for an author, to be bundled into a
95       distribution. Over time, this has created a lot of wasted space on CPAN
96       mirrors. Module::Package fixes this.
97
98   Collaborator Plugin Discovery
99       An increasing problem with Module::Install is that when people check
100       out your module source from a repository, they don't know which
101       Module::Install plugin modules you have used. That's because the
102       Makefile.PL only requires the function names, not the module names that
103       they come from.
104
105       Many people have realized this problem, and worked around it in various
106       suboptimal ways. Module::Package manages this problem for you.
107
108   Feature Grouping and Reuse
109       Module::Install has lots of plugins. Although it is possible with plain
110       Module::Install, nobody seems to make plugins that group other plugins.
111       This also might introduce subtle problems of using groups with other
112       groups.
113
114       Module::Package has object oriented plugins whose main purpose is to
115       create these groups. They inherit base functionality, subclass it to
116       their design goals and can define options for the user to tweak how
117       they will operate.
118

USAGE

120       The basic anatomy of a Makefile.PL call to Module::Package is:
121
122           use inc::Module::Package 'PluginName:flavor <version>',
123               $option1 => $value1;
124
125       The "inc::Module::Package" part uses the Module::Install "inc"
126       bootstrapping trick.
127
128       "PluginName:flavor" (note the single ':') resolves to the inline class
129       "Module::Package::PluginName::flavor", within the module
130       "Module::Package::PluginName". Module::Package::PluginName::flavor must
131       be a subclass of Module::Package::Plugin.
132
133       An optional version can be used after the plugin name.
134
135       Optional key/value pairs can follow the Plugin specification. They are
136       used to pass information to the plugin. See Plugin docs for more
137       details.
138
139       If ":flavor" is omitted, the class Module::Package::PluginName is used.
140       The idea is that you can create a single module with many different
141       plugin styles.
142
143       If "PluginName" is omitted, then ":flavor" is used against
144       Module::Package::Plugin. These are a set of common plugin classes that
145       you can use.
146
147       If "PluginName:flavor" is omitted altogether, it is the same as saying
148       'Plugin:basic'. Note that you need to specify the ':basic' plugin if
149       you want to also pass it options.
150

STATUS

152       This is still an early release. We are still shaking out the bugs. You
153       might want to hold off for a bit longer before using Module::Package
154       for important modules.
155
156
157
158perl v5.28.0                      2011-10-06                Module::Package(3)
Impressum