1Module::Package(3) User Contributed Perl Documentation Module::Package(3)
2
6 In your "Makefile.PL":
7 use inc::Module::Package;
9 or one of these invocations:
11 # These two are functionally the same as above:
13 use inc::Module::Package ':basic';
14 use inc::Module::Package 'Plugin:basic';
15 # With Module::Package::Catalyst plugin options
17 use inc::Module::Package 'Catalyst';
18 # With Module::Package::Catalyst::common inline plugin class
20 use inc::Module::Package 'Catalyst:common';
21 # Pass options to the Module::Package::Ingy::modern constructor
23 use inc::Module::Package 'Ingy:modern',
24 option1 => 'value1',
25 option2 => 'value2';
26
28 This module is a dropin replacement for Module::Install. It does
29 everything Module::Install does, but just a bit better.
30 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
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 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 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 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 use inc::Module::Package 'Catalyst:widget';
58 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 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 use inc::Module::Package 'Catalyst:widget',
70 deps_list => 0,
71 some_cataylst_thing => '...';
72 # All Module::Install plugins still work!
74 requires 'Some::Module' => 3.14;
75 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 The point here is that with Module::Package, module packaging just got
81 a whole lot more powerful and simple. A rare combination!
82
84 Module::Package has many advantages over vanilla Module::Install.
85 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 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 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 Many people have realized this problem, and worked around it in various
106 suboptimal ways. Module::Package manages this problem for you.
107 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 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
120 The basic anatomy of a Makefile.PL call to Module::Package is:
121 use inc::Module::Package 'PluginName:flavor <version>',
123 $option1 => $value1;
124 The "inc::Module::Package" part uses the Module::Install "inc"
126 bootstrapping trick.
127 "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 An optional version can be used after the plugin name.
134 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 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 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 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
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.
155perl v5.36.0 2023-01-20 Module::Package(3)