1Module::Build::Cookbook(P3eprml)Programmers Reference GMuoidduele::Build::Cookbook(3pm)
2
3
4

NAME

6       Module::Build::Cookbook - Examples of Module::Build Usage
7

DESCRIPTION

9       "Module::Build" isn't conceptually very complicated, but examples are
10       always helpful.  The following recipes should help developers and/or
11       installers put together the pieces from the other parts of the
12       documentation.
13

BASIC RECIPES

15   Installing modules that use Module::Build
16       In most cases, you can just issue the following commands:
17
18         perl Build.PL
19         ./Build
20         ./Build test
21         ./Build install
22
23       There's nothing complicated here - first you're running a script called
24       Build.PL, then you're running a (newly-generated) script called Build
25       and passing it various arguments.
26
27       The exact commands may vary a bit depending on how you invoke perl
28       scripts on your system.  For instance, if you have multiple versions of
29       perl installed, you can install to one particular perl's library
30       directories like so:
31
32         /usr/bin/perl5.8.1 Build.PL
33         ./Build
34         ./Build test
35         ./Build install
36
37       If you're on Windows where the current directory is always searched
38       first for scripts, you'll probably do something like this:
39
40         perl Build.PL
41         Build
42         Build test
43         Build install
44
45       On the old Mac OS (version 9 or lower) using MacPerl, you can double-
46       click on the Build.PL script to create the Build script, then double-
47       click on the Build script to run its "build", "test", and "install"
48       actions.
49
50       The Build script knows what perl was used to run Build.PL, so you don't
51       need to re-invoke the Build script with the complete perl path each
52       time.  If you invoke it with the wrong perl path, you'll get a warning
53       or a fatal error.
54
55   Modifying Config.pm values
56       "Module::Build" relies heavily on various values from perl's
57       "Config.pm" to do its work.  For example, default installation paths
58       are given by "installsitelib" and "installvendorman3dir" and friends, C
59       linker & compiler settings are given by "ld", "lddlflags", "cc",
60       "ccflags", and so on.  If you're pretty sure you know what you're
61       doing, you can tell "Module::Build" to pretend there are different
62       values in Config.pm than what's really there, by passing arguments for
63       the "--config" parameter on the command line:
64
65         perl Build.PL --config cc=gcc --config ld=gcc
66
67       Inside the "Build.PL" script the same thing can be accomplished by
68       passing values for the "config" parameter to "new()":
69
70        my $build = Module::Build->new
71          (
72           ...
73           config => { cc => 'gcc', ld => 'gcc' },
74           ...
75          );
76
77       In custom build code, the same thing can be accomplished by calling the
78       "config" in Module::Build method:
79
80        $build->config( cc => 'gcc' );     # Set
81        $build->config( ld => 'gcc' );     # Set
82        ...
83        my $linker = $build->config('ld'); # Get
84
85   Installing modules using the programmatic interface
86       If you need to build, test, and/or install modules from within some
87       other perl code (as opposed to having the user type installation
88       commands at the shell), you can use the programmatic interface.  Create
89       a Module::Build object (or an object of a custom Module::Build
90       subclass) and then invoke its "dispatch()" method to run various
91       actions.
92
93         my $build = Module::Build->new
94           (
95            module_name => 'Foo::Bar',
96            license     => 'perl',
97            requires    => { 'Some::Module'   => '1.23' },
98           );
99         $build->dispatch('build');
100         $build->dispatch('test', verbose => 1);
101         $build->dispatch('install');
102
103       The first argument to "dispatch()" is the name of the action, and any
104       following arguments are named parameters.
105
106       This is the interface we use to test Module::Build itself in the
107       regression tests.
108
109   Installing to a temporary directory
110       To create packages for package managers like RedHat's "rpm" or Debian's
111       "deb", you may need to install to a temporary directory first and then
112       create the package from that temporary installation.  To do this,
113       specify the "destdir" parameter to the "install" action:
114
115         ./Build install --destdir /tmp/my-package-1.003
116
117       This essentially just prepends all the installation paths with the
118       /tmp/my-package-1.003 directory.
119
120   Installing to a non-standard directory
121       To install to a non-standard directory (for example, if you don't have
122       permission to install in the system-wide directories), you can use the
123       "install_base" or "prefix" parameters:
124
125         ./Build install --install_base /foo/bar
126
127       See "INSTALL PATHS" in Module::Build for a much more complete
128       discussion of how installation paths are determined.
129
130   Installing in the same location as ExtUtils::MakeMaker
131       With the introduction of "--prefix" in Module::Build 0.28 and
132       "INSTALL_BASE" in "ExtUtils::MakeMaker" 6.31 its easy to get them both
133       to install to the same locations.
134
135       First, ensure you have at least version 0.28 of Module::Build installed
136       and 6.31 of "ExtUtils::MakeMaker".  Prior versions have differing (and
137       in some cases quite strange) installation behaviors.
138
139       The following installation flags are equivalent between
140       "ExtUtils::MakeMaker" and "Module::Build".
141
142           MakeMaker             Module::Build
143           PREFIX=...            --prefix ...
144           INSTALL_BASE=...      --install_base ...
145           DESTDIR=...           --destdir ...
146           LIB=...               --install_path lib=...
147           INSTALLDIRS=...       --installdirs ...
148           INSTALLDIRS=perl      --installdirs core
149           UNINST=...            --uninst ...
150           INC=...               --extra_compiler_flags ...
151           POLLUTE=1             --extra_compiler_flags -DPERL_POLLUTE
152
153       For example, if you are currently installing "MakeMaker" modules with
154       this command:
155
156           perl Makefile.PL PREFIX=~
157           make test
158           make install UNINST=1
159
160       You can install into the same location with Module::Build using this:
161
162           perl Build.PL --prefix ~
163           ./Build test
164           ./Build install --uninst 1
165
166       "prefix" vs "install_base"
167
168       The behavior of "prefix" is complicated and depends on how your Perl is
169       configured.  The resulting installation locations will vary from
170       machine to machine and even different installations of Perl on the same
171       machine.  Because of this, it's difficult to document where "prefix"
172       will place your modules.
173
174       In contrast, "install_base" has predictable, easy to explain
175       installation locations.  Now that "Module::Build" and "MakeMaker" both
176       have "install_base" there is little reason to use "prefix" other than
177       to preserve your existing installation locations.  If you are starting
178       a fresh Perl installation we encourage you to use "install_base".  If
179       you have an existing installation installed via "prefix", consider
180       moving it to an installation structure matching "install_base" and
181       using that instead.
182
183   Running a single test file
184       "Module::Build" supports running a single test, which enables you to
185       track down errors more quickly.  Use the following format:
186
187         ./Build test --test_files t/mytest.t
188
189       In addition, you may want to run the test in verbose mode to get more
190       informative output:
191
192         ./Build test --test_files t/mytest.t --verbose 1
193
194       I run this so frequently that I define the following shell alias:
195
196         alias t './Build test --verbose 1 --test_files'
197
198       So then I can just execute "t t/mytest.t" to run a single test.
199

ADVANCED RECIPES

201   Making a CPAN.pm-compatible distribution
202       New versions of CPAN.pm understand how to use a Build.PL script, but
203       old versions don't.  If authors want to help users who have old
204       versions, some form of Makefile.PL should be supplied.  The easiest way
205       to accomplish this is to use the "create_makefile_pl" parameter to
206       "Module::Build->new()" in the "Build.PL" script, which can create
207       various flavors of Makefile.PL during the "dist" action.
208
209       As a best practice, we recommend using the "traditional" style of
210       Makefile.PL unless your distribution has needs that can't be
211       accomplished that way.
212
213       The "Module::Build::Compat" module, which is part of "Module::Build"'s
214       distribution, is responsible for creating these Makefile.PLs.  Please
215       see Module::Build::Compat for the details.
216
217   Changing the order of the build process
218       The "build_elements" property specifies the steps "Module::Build" will
219       take when building a distribution.  To change the build order, change
220       the order of the entries in that property:
221
222         # Process pod files first
223         my @e = @{$build->build_elements};
224         my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
225         unshift @e, splice @e, $i, 1;
226
227       Currently, "build_elements" has the following default value:
228
229         [qw( PL support pm xs pod script )]
230
231       Do take care when altering this property, since there may be non-
232       obvious (and non-documented!) ordering dependencies in the
233       "Module::Build" code.
234
235   Adding new file types to the build process
236       Sometimes you might have extra types of files that you want to install
237       alongside the standard types like .pm and .pod files.  For instance,
238       you might have a Bar.dat file containing some data related to the
239       "Foo::Bar" module and you'd like for it to end up as Foo/Bar.dat
240       somewhere in perl's @INC path so "Foo::Bar" can access it easily at
241       runtime.  The following code from a sample "Build.PL" file demonstrates
242       how to accomplish this:
243
244         use Module::Build;
245         my $build = Module::Build->new
246           (
247            module_name => 'Foo::Bar',
248            ...other stuff here...
249           );
250         $build->add_build_element('dat');
251         $build->create_build_script;
252
253       This will find all .dat files in the lib/ directory, copy them to the
254       blib/lib/ directory during the "build" action, and install them during
255       the "install" action.
256
257       If your extra files aren't located in the "lib/" directory in your
258       distribution, you can explicitly say where they are, just as you'd do
259       with .pm or .pod files:
260
261         use Module::Build;
262         my $build = new Module::Build
263           (
264            module_name => 'Foo::Bar',
265            dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
266            ...other stuff here...
267           );
268         $build->add_build_element('dat');
269         $build->create_build_script;
270
271       If your extra files actually need to be created on the user's machine,
272       or if they need some other kind of special processing, you'll probably
273       want to subclass "Module::Build" and create a special method to process
274       them, named "process_${kind}_files()":
275
276         use Module::Build;
277         my $class = Module::Build->subclass(code => <<'EOF');
278           sub process_dat_files {
279             my $self = shift;
280             ... locate and process *.dat files,
281             ... and create something in blib/lib/
282           }
283         EOF
284         my $build = $class->new
285           (
286            module_name => 'Foo::Bar',
287            ...other stuff here...
288           );
289         $build->add_build_element('dat');
290         $build->create_build_script;
291
292       If your extra files don't go in lib/ but in some other place, see
293       "Adding new elements to the install process" for how to actually get
294       them installed.
295
296       Please note that these examples use some capabilities of Module::Build
297       that first appeared in version 0.26.  Before that it could still be
298       done, but the simple cases took a bit more work.
299
300   Adding new elements to the install process
301       By default, Module::Build creates seven subdirectories of the blib
302       directory during the build process: lib, arch, bin, script, bindoc,
303       libdoc, and html (some of these may be missing or empty if there's
304       nothing to go in them).  Anything copied to these directories during
305       the build will eventually be installed during the "install" action (see
306       "INSTALL PATHS" in Module::Build.
307
308       If you need to create a new custom type of installable element, e.g.
309       "conf", then you need to tell Module::Build where things in blib/conf/
310       should be installed.  To do this, use the "install_path" parameter to
311       the "new()" method:
312
313         my $build = Module::Build->new
314           (
315            ...other stuff here...
316            install_path => { conf => $installation_path }
317           );
318
319       Or you can call the "install_path()" method later:
320
321         $build->install_path(conf => $installation_path);
322
323       The user may also specify the path on the command line:
324
325         perl Build.PL --install_path conf=/foo/path/etc
326
327       The important part, though, is that somehow the install path needs to
328       be set, or else nothing in the blib/conf/ directory will get installed,
329       and a runtime error during the "install" action will result.
330
331       See also "Adding new file types to the build process" for how to create
332       the stuff in blib/conf/ in the first place.
333

EXAMPLES ON CPAN

335       Several distributions on CPAN are making good use of various features
336       of Module::Build.  They can serve as real-world examples for others.
337
338   SVN-Notify-Mirror
339       http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/
340       <http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
341
342       John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
343
344       1. Using "auto_features", I check to see whether two optional modules
345       are available - SVN::Notify::Config and Net::SSH;
346       2. If the S::N::Config module is loaded, I automatically generate test
347       files for it during Build (using the "PL_files" property).
348       3. If the "ssh_feature" is available, I ask if the user wishes to
349       perform the ssh tests (since it requires a little preliminary setup);
350       4. Only if the user has "ssh_feature" and answers yes to the testing,
351       do I generate a test file.
352           I'm sure I could not have handled this complexity with EU::MM, but
353           it was very easy to do with M::B.
354
355   Modifying an action
356       Sometimes you might need an to have an action, say "./Build install",
357       do something unusual.  For instance, you might need to change the
358       ownership of a file or do something else peculiar to your application.
359
360       You can subclass "Module::Build" on the fly using the "subclass()"
361       method and override the methods that perform the actions.  You may need
362       to read through "Module::Build::Authoring" and "Module::Build::API" to
363       find the methods you want to override.  All "action" methods are
364       implemented by a method called "ACTION_" followed by the action's name,
365       so here's an example of how it would work for the "install" action:
366
367         # Build.PL
368         use Module::Build;
369         my $class = Module::Build->subclass(
370             class => "Module::Build::Custom",
371             code => <<'SUBCLASS' );
372
373         sub ACTION_install {
374             my $self = shift;
375             # YOUR CODE HERE
376             $self->SUPER::ACTION_install;
377         }
378         SUBCLASS
379
380         $class->new(
381             module_name => 'Your::Module',
382             # rest of the usual Module::Build parameters
383         )->create_build_script;
384
385   Adding an action
386       You can add a new "./Build" action simply by writing the method for it
387       in your subclass.  Use "depends_on" to declare that another action must
388       have been run before your action.
389
390       For example, let's say you wanted to be able to write "./Build commit"
391       to test your code and commit it to Subversion.
392
393         # Build.PL
394         use Module::Build;
395         my $class = Module::Build->subclass(
396             class => "Module::Build::Custom",
397             code => <<'SUBCLASS' );
398
399         sub ACTION_commit {
400             my $self = shift;
401
402             $self->depends_on("test");
403             $self->do_system(qw(svn commit));
404         }
405         SUBCLASS
406
407   Bundling Module::Build
408       Note: This section probably needs an update as the technology improves
409       (see contrib/bundle.pl in the distribution).
410
411       Suppose you want to use some new-ish features of Module::Build, e.g.
412       newer than the version of Module::Build your users are likely to
413       already have installed on their systems.  The first thing you should do
414       is set "configure_requires" to your minimum version of Module::Build.
415       See Module::Build::Authoring.
416
417       But not every build system honors "configure_requires" yet.  Here's how
418       you can ship a copy of Module::Build, but still use a newer installed
419       version to take advantage of any bug fixes and upgrades.
420
421       First, install Module::Build into Your-Project/inc/Module-Build.  CPAN
422       will not index anything in the inc directory so this copy will not show
423       up in CPAN searches.
424
425           cd Module-Build
426           perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
427           ./Build test
428           ./Build install
429
430       You should now have all the Module::Build .pm files in
431       Your-Project/inc/Module-Build/lib/perl5.
432
433       Next, add this to the top of your Build.PL.
434
435           my $Bundled_MB = 0.30;  # or whatever version it was.
436
437           # Find out what version of Module::Build is installed or fail quietly.
438           # This should be cross-platform.
439           my $Installed_MB =
440               `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1";
441
442           # some operating systems put a newline at the end of every print.
443           chomp $Installed_MB;
444
445           $Installed_MB = 0 if $?;
446
447           # Use our bundled copy of Module::Build if it's newer than the installed.
448           unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
449
450           require Module::Build;
451
452       And write the rest of your Build.PL normally.  Module::Build will
453       remember your change to @INC and use it when you run ./Build.
454
455       In the future, we hope to provide a more automated solution for this
456       scenario; see "inc/latest.pm" in the Module::Build distribution for one
457       indication of the direction we're moving.
458

AUTHOR

460       Ken Williams <kwilliams@cpan.org>
461
463       Copyright (c) 2001-2008 Ken Williams.  All rights reserved.
464
465       This library is free software; you can redistribute it and/or modify it
466       under the same terms as Perl itself.
467

SEE ALSO

469       perl(1), Module::Build(3), Module::Build::Authoring(3),
470       Module::Build::API(3)
471
472
473
474perl v5.12.4                      2011-06-07      Module::Build::Cookbook(3pm)
Impressum