1Module::Build::CookbookU(s3e)r Contributed Perl DocumentaMtoidounle::Build::Cookbook(3)
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 actions.
91
92         my $build = Module::Build->new
93           (
94            module_name => 'Foo::Bar',
95            license     => 'perl',
96            requires    => { 'Some::Module'   => '1.23' },
97           );
98         $build->dispatch('build');
99         $build->dispatch('test', verbose => 1);
100         $build->dispatch('install');
101
102       The first argument to dispatch() is the name of the action, and any
103       following arguments are named parameters.
104
105       This is the interface we use to test Module::Build itself in the
106       regression tests.
107
108   Installing to a temporary directory
109       To create packages for package managers like RedHat's "rpm" or Debian's
110       "deb", you may need to install to a temporary directory first and then
111       create the package from that temporary installation.  To do this,
112       specify the "destdir" parameter to the "install" action:
113
114         ./Build install --destdir /tmp/my-package-1.003
115
116       This essentially just prepends all the installation paths with the
117       /tmp/my-package-1.003 directory.
118
119   Installing to a non-standard directory
120       To install to a non-standard directory (for example, if you don't have
121       permission to install in the system-wide directories), you can use the
122       "install_base" or "prefix" parameters:
123
124         ./Build install --install_base /foo/bar
125
126       See "INSTALL PATHS" in Module::Build for a much more complete
127       discussion of how installation paths are determined.
128
129   Installing in the same location as ExtUtils::MakeMaker
130       With the introduction of "--prefix" in Module::Build 0.28 and
131       "INSTALL_BASE" in "ExtUtils::MakeMaker" 6.31 its easy to get them both
132       to install to the same locations.
133
134       First, ensure you have at least version 0.28 of Module::Build installed
135       and 6.31 of "ExtUtils::MakeMaker".  Prior versions have differing (and
136       in some cases quite strange) installation behaviors.
137
138       The following installation flags are equivalent between
139       "ExtUtils::MakeMaker" and "Module::Build".
140
141           MakeMaker             Module::Build
142           PREFIX=...            --prefix ...
143           INSTALL_BASE=...      --install_base ...
144           DESTDIR=...           --destdir ...
145           LIB=...               --install_path lib=...
146           INSTALLDIRS=...       --installdirs ...
147           INSTALLDIRS=perl      --installdirs core
148           UNINST=...            --uninst ...
149           INC=...               --extra_compiler_flags ...
150           POLLUTE=1             --extra_compiler_flags -DPERL_POLLUTE
151
152       For example, if you are currently installing "MakeMaker" modules with
153       this command:
154
155           perl Makefile.PL PREFIX=~
156           make test
157           make install UNINST=1
158
159       You can install into the same location with Module::Build using this:
160
161           perl Build.PL --prefix ~
162           ./Build test
163           ./Build install --uninst 1
164
165       "prefix" vs "install_base"
166
167       The behavior of "prefix" is complicated and depends on how your Perl is
168       configured.  The resulting installation locations will vary from
169       machine to machine and even different installations of Perl on the same
170       machine.  Because of this, it's difficult to document where "prefix"
171       will place your modules.
172
173       In contrast, "install_base" has predictable, easy to explain
174       installation locations.  Now that "Module::Build" and "MakeMaker" both
175       have "install_base" there is little reason to use "prefix" other than
176       to preserve your existing installation locations.  If you are starting
177       a fresh Perl installation we encourage you to use "install_base".  If
178       you have an existing installation installed via "prefix", consider
179       moving it to an installation structure matching "install_base" and
180       using that instead.
181
182   Running a single test file
183       "Module::Build" supports running a single test, which enables you to
184       track down errors more quickly.  Use the following format:
185
186         ./Build test --test_files t/mytest.t
187
188       In addition, you may want to run the test in verbose mode to get more
189       informative output:
190
191         ./Build test --test_files t/mytest.t --verbose 1
192
193       I run this so frequently that I define the following shell alias:
194
195         alias t './Build test --verbose 1 --test_files'
196
197       So then I can just execute "t t/mytest.t" to run a single test.
198

ADVANCED RECIPES

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

EXAMPLES ON CPAN

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

AUTHOR

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

SEE ALSO

467       perl(1), Module::Build(3), Module::Build::Authoring(3),
468       Module::Build::API(3)
469
470
471
472perl v5.36.0                      2023-01-20        Module::Build::Cookbook(3)
Impressum