1Module::Build::Compat(3pPme)rl Programmers Reference GuiMdoedule::Build::Compat(3pm)
2
6 Module::Build::Compat - Compatibility with ExtUtils::MakeMaker
7
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
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 "Module::Build::Compat" also provides some code that helps out the
26 Makefile.PL at runtime.
27
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 The currently supported styles are:
38 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 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 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 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 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 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 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 "run_build_pl()" accepts the following named parameters:
85 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 script
92 This is the filename of the script to run - it defaults to
93 "Build.PL".
94 write_makefile()
96 This method writes a 'dummy' Makefile that will pass all commands
97 through to the corresponding "Module::Build" actions.
98 "write_makefile()" accepts the following named parameters:
100 makefile
102 The name of the file to write - defaults to the string
103 "Makefile".
104
106 So, some common scenarios are:
107 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 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 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 For good measure, of course, test both the Makefile.PL and the
126 Build.PL before shipping.
127 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
136 Ken Williams <kwilliams@cpan.org>
137
139 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
140 This library is free software; you can redistribute it and/or modify it
142 under the same terms as Perl itself.
143
145 Module::Build(3), ExtUtils::MakeMaker(3)
146perl v5.12.4 2011-06-07 Module::Build::Compat(3pm)