1Module::Build::Compat(3U)ser Contributed Perl DocumentatiMoondule::Build::Compat(3)
2
3
4

NAME

6       Module::Build::Compat - Compatibility with ExtUtils::MakeMaker
7

SYNOPSIS

9         # In a Build.PL :
10         use Module::Build;
11         my $build = Module::Build->new
12           ( module_name => 'Foo::Bar',
13             license     => 'perl',
14             create_makefile_pl => 'traditional' );
15         ...
16

DESCRIPTION

18       Because "ExtUtils::MakeMaker" has been the standard way to distribute
19       modules for a long time, many tools (CPAN.pm, or your system
20       administrator) may expect to find a working Makefile.PL in every
21       distribution they download from CPAN.  If you want to throw them a
22       bone, you can use "Module::Build::Compat" to automatically generate a
23       Makefile.PL for you, in one of several different styles.
24
25       "Module::Build::Compat" also provides some code that helps out the
26       Makefile.PL at runtime.
27

METHODS

29       create_makefile_pl($style, $build)
30           Creates a Makefile.PL in the current directory in one of several
31           styles, based on the supplied "Module::Build" object $build.  This
32           is typically controlled by passing the desired style as the
33           "create_makefile_pl" parameter to "Module::Build"'s "new()" method;
34           the Makefile.PL will then be automatically created during the
35           "distdir" action.
36
37           The currently supported styles are:
38
39           traditional
40               A Makefile.PL will be created in the "traditional" style, i.e.
41               it will use "ExtUtils::MakeMaker" and won't rely on
42               "Module::Build" at all.  In order to create the Makefile.PL,
43               we'll include the "requires" and "build_requires" dependencies
44               as the "PREREQ_PM" parameter.
45
46               You don't want to use this style if during the "perl Build.PL"
47               stage you ask the user questions, or do some auto-sensing about
48               the user's environment, or if you subclass "Module::Build" to
49               do some customization, because the vanilla Makefile.PL won't do
50               any of that.
51
52           small
53               A small Makefile.PL will be created that passes all
54               functionality through to the Build.PL script in the same
55               directory.  The user must already have "Module::Build"
56               installed in order to use this, or else they'll get a module-
57               not-found error.
58
59           passthrough (DEPRECATED)
60               This is just like the "small" option above, but if
61               "Module::Build" is not already installed on the user's system,
62               the script will offer to use "CPAN.pm" to download it and
63               install it before continuing with the build.
64
65               This option has been deprecated and may be removed in a future
66               version of Module::Build.  Modern CPAN.pm and CPANPLUS will
67               recognize the "configure_requires" metadata property and
68               install Module::Build before running Build.PL if Module::Build
69               is listed and Module::Build now adds itself to
70               configure_requires by default.
71
72               Perl 5.10.1 includes "configure_requires" support.  In the
73               future, when "configure_requires" support is deemed
74               sufficiently widespread, the "passthrough" style will be
75               removed.
76
77       run_build_pl(args => \@ARGV)
78           This method runs the Build.PL script, passing it any arguments the
79           user may have supplied to the "perl Makefile.PL" command.  Because
80           "ExtUtils::MakeMaker" and "Module::Build" accept different
81           arguments, this method also performs some translation between the
82           two.
83
84           "run_build_pl()" accepts the following named parameters:
85
86           args
87               The "args" parameter specifies the parameters that would
88               usually appear on the command line of the "perl Makefile.PL"
89               command - typically you'll just pass a reference to @ARGV.
90
91           script
92               This is the filename of the script to run - it defaults to
93               "Build.PL".
94
95       write_makefile()
96           This method writes a 'dummy' Makefile that will pass all commands
97           through to the corresponding "Module::Build" actions.
98
99           "write_makefile()" accepts the following named parameters:
100
101           makefile
102               The name of the file to write - defaults to the string
103               "Makefile".
104

SCENARIOS

106       So, some common scenarios are:
107
108       1.  Just include a Build.PL script (without a Makefile.PL script), and
109           give installation directions in a README or INSTALL document
110           explaining how to install the module.  In particular, explain that
111           the user must install "Module::Build" before installing your
112           module.
113
114           Note that if you do this, you may make things easier for yourself,
115           but harder for people with older versions of CPAN or CPANPLUS on
116           their system, because those tools generally only understand the
117           Makefile.PL/"ExtUtils::MakeMaker" way of doing things.
118
119       2.  Include a Build.PL script and a "traditional" Makefile.PL, created
120           either manually or with "create_makefile_pl()".  Users won't ever
121           have to install "Module::Build" if they use the Makefile.PL, but
122           they won't get to take advantage of "Module::Build"'s extra
123           features either.
124
125           For good measure, of course, test both the Makefile.PL and the
126           Build.PL before shipping.
127
128       3.  Include a Build.PL script and a "pass-through" Makefile.PL built
129           using "Module::Build::Compat".  This will mean that people can
130           continue to use the "old" installation commands, and they may never
131           notice that it's actually doing something else behind the scenes.
132           It will also mean that your installation process is compatible with
133           older versions of tools like CPAN and CPANPLUS.
134

AUTHOR

136       Ken Williams <kwilliams@cpan.org>
137
139       Copyright (c) 2001-2006 Ken Williams.  All rights reserved.
140
141       This library is free software; you can redistribute it and/or modify it
142       under the same terms as Perl itself.
143

SEE ALSO

145       Module::Build(3), ExtUtils::MakeMaker(3)
146
147
148
149perl v5.16.3                      2014-06-10          Module::Build::Compat(3)
Impressum