1package Module::Build::Cookbook; 2use strict; 3use vars qw($VERSION); 4$VERSION = '0.34'; 5 6 7=head1 NAME 8 9Module::Build::Cookbook - Examples of Module::Build Usage 10 11=head1 DESCRIPTION 12 13C<Module::Build> isn't conceptually very complicated, but examples are 14always helpful. The following recipes should help developers and/or 15installers put together the pieces from the other parts of the 16documentation. 17 18 19=head1 BASIC RECIPES 20 21 22=head2 Installing modules that use Module::Build 23 24In most cases, you can just issue the following commands: 25 26 perl Build.PL 27 ./Build 28 ./Build test 29 ./Build install 30 31There's nothing complicated here - first you're running a script 32called F<Build.PL>, then you're running a (newly-generated) script 33called F<Build> and passing it various arguments. 34 35The exact commands may vary a bit depending on how you invoke perl 36scripts on your system. For instance, if you have multiple versions 37of perl installed, you can install to one particular perl's library 38directories like so: 39 40 /usr/bin/perl5.8.1 Build.PL 41 ./Build 42 ./Build test 43 ./Build install 44 45If you're on Windows where the current directory is always searched 46first for scripts, you'll probably do something like this: 47 48 perl Build.PL 49 Build 50 Build test 51 Build install 52 53On the old Mac OS (version 9 or lower) using MacPerl, you can 54double-click on the F<Build.PL> script to create the F<Build> script, 55then double-click on the F<Build> script to run its C<build>, C<test>, 56and C<install> actions. 57 58The F<Build> script knows what perl was used to run F<Build.PL>, so 59you don't need to re-invoke the F<Build> script with the complete perl 60path each time. If you invoke it with the I<wrong> perl path, you'll 61get a warning or a fatal error. 62 63=head2 Modifying Config.pm values 64 65C<Module::Build> relies heavily on various values from perl's 66C<Config.pm> to do its work. For example, default installation paths 67are given by C<installsitelib> and C<installvendorman3dir> and 68friends, C linker & compiler settings are given by C<ld>, 69C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure 70you know what you're doing>, you can tell C<Module::Build> to pretend 71there are different values in F<Config.pm> than what's really there, 72by passing arguments for the C<--config> parameter on the command 73line: 74 75 perl Build.PL --config cc=gcc --config ld=gcc 76 77Inside the C<Build.PL> script the same thing can be accomplished by 78passing values for the C<config> parameter to C<new()>: 79 80 my $build = Module::Build->new 81 ( 82 ... 83 config => { cc => 'gcc', ld => 'gcc' }, 84 ... 85 ); 86 87In custom build code, the same thing can be accomplished by calling 88the L<Module::Build/config> method: 89 90 $build->config( cc => 'gcc' ); # Set 91 $build->config( ld => 'gcc' ); # Set 92 ... 93 my $linker = $build->config('ld'); # Get 94 95 96=head2 Installing modules using the programmatic interface 97 98If you need to build, test, and/or install modules from within some 99other perl code (as opposed to having the user type installation 100commands at the shell), you can use the programmatic interface. 101Create a Module::Build object (or an object of a custom Module::Build 102subclass) and then invoke its C<dispatch()> method to run various 103actions. 104 105 my $build = Module::Build->new 106 ( 107 module_name => 'Foo::Bar', 108 license => 'perl', 109 requires => { 'Some::Module' => '1.23' }, 110 ); 111 $build->dispatch('build'); 112 $build->dispatch('test', verbose => 1); 113 $build->dispatch('install'); 114 115The first argument to C<dispatch()> is the name of the action, and any 116following arguments are named parameters. 117 118This is the interface we use to test Module::Build itself in the 119regression tests. 120 121 122=head2 Installing to a temporary directory 123 124To create packages for package managers like RedHat's C<rpm> or 125Debian's C<deb>, you may need to install to a temporary directory 126first and then create the package from that temporary installation. 127To do this, specify the C<destdir> parameter to the C<install> action: 128 129 ./Build install --destdir /tmp/my-package-1.003 130 131This essentially just prepends all the installation paths with the 132F</tmp/my-package-1.003> directory. 133 134 135=head2 Installing to a non-standard directory 136 137To install to a non-standard directory (for example, if you don't have 138permission to install in the system-wide directories), you can use the 139C<install_base> or C<prefix> parameters: 140 141 ./Build install --install_base /foo/bar 142 143See L<Module::Build/"INSTALL PATHS"> for a much more complete 144discussion of how installation paths are determined. 145 146 147=head2 Installing in the same location as ExtUtils::MakeMaker 148 149With the introduction of C<--prefix> in Module::Build 0.28 and 150C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both 151to install to the same locations. 152 153First, ensure you have at least version 0.28 of Module::Build 154installed and 6.31 of C<ExtUtils::MakeMaker>. Prior versions have 155differing (and in some cases quite strange) installation behaviors. 156 157The following installation flags are equivalent between 158C<ExtUtils::MakeMaker> and C<Module::Build>. 159 160 MakeMaker Module::Build 161 PREFIX=... --prefix ... 162 INSTALL_BASE=... --install_base ... 163 DESTDIR=... --destdir ... 164 LIB=... --install_path lib=... 165 INSTALLDIRS=... --installdirs ... 166 INSTALLDIRS=perl --installdirs core 167 UNINST=... --uninst ... 168 INC=... --extra_compiler_flags ... 169 POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE 170 171For example, if you are currently installing C<MakeMaker> modules with 172this command: 173 174 perl Makefile.PL PREFIX=~ 175 make test 176 make install UNINST=1 177 178You can install into the same location with Module::Build using this: 179 180 perl Build.PL --prefix ~ 181 ./Build test 182 ./Build install --uninst 1 183 184=head3 C<prefix> vs C<install_base> 185 186The behavior of C<prefix> is complicated and depends on 187how your Perl is configured. The resulting installation locations 188will vary from machine to machine and even different installations of 189Perl on the same machine. Because of this, it's difficult to document 190where C<prefix> will place your modules. 191 192In contrast, C<install_base> has predictable, easy to explain 193installation locations. Now that C<Module::Build> and C<MakeMaker> both 194have C<install_base> there is little reason to use C<prefix> other 195than to preserve your existing installation locations. If you are 196starting a fresh Perl installation we encourage you to use 197C<install_base>. If you have an existing installation installed via 198C<prefix>, consider moving it to an installation structure matching 199C<install_base> and using that instead. 200 201 202=head2 Running a single test file 203 204C<Module::Build> supports running a single test, which enables you to 205track down errors more quickly. Use the following format: 206 207 ./Build test --test_files t/mytest.t 208 209In addition, you may want to run the test in verbose mode to get more 210informative output: 211 212 ./Build test --test_files t/mytest.t --verbose 1 213 214I run this so frequently that I define the following shell alias: 215 216 alias t './Build test --verbose 1 --test_files' 217 218So then I can just execute C<t t/mytest.t> to run a single test. 219 220 221=head1 ADVANCED RECIPES 222 223 224=head2 Making a CPAN.pm-compatible distribution 225 226New versions of CPAN.pm understand how to use a F<Build.PL> script, 227but old versions don't. If authors want to help users who have old 228versions, some form of F<Makefile.PL> should be supplied. The easiest 229way to accomplish this is to use the C<create_makefile_pl> parameter to 230C<< Module::Build->new() >> in the C<Build.PL> script, which can 231create various flavors of F<Makefile.PL> during the C<dist> action. 232 233As a best practice, we recommend using the "traditional" style of 234F<Makefile.PL> unless your distribution has needs that can't be 235accomplished that way. 236 237The C<Module::Build::Compat> module, which is part of 238C<Module::Build>'s distribution, is responsible for creating these 239F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details. 240 241 242=head2 Changing the order of the build process 243 244The C<build_elements> property specifies the steps C<Module::Build> 245will take when building a distribution. To change the build order, 246change the order of the entries in that property: 247 248 # Process pod files first 249 my @e = @{$build->build_elements}; 250 my ($i) = grep {$e[$_] eq 'pod'} 0..$#e; 251 unshift @e, splice @e, $i, 1; 252 253Currently, C<build_elements> has the following default value: 254 255 [qw( PL support pm xs pod script )] 256 257Do take care when altering this property, since there may be 258non-obvious (and non-documented!) ordering dependencies in the 259C<Module::Build> code. 260 261 262=head2 Adding new file types to the build process 263 264Sometimes you might have extra types of files that you want to install 265alongside the standard types like F<.pm> and F<.pod> files. For 266instance, you might have a F<Bar.dat> file containing some data 267related to the C<Foo::Bar> module and you'd like for it to end up as 268F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can 269access it easily at runtime. The following code from a sample 270C<Build.PL> file demonstrates how to accomplish this: 271 272 use Module::Build; 273 my $build = Module::Build->new 274 ( 275 module_name => 'Foo::Bar', 276 ...other stuff here... 277 ); 278 $build->add_build_element('dat'); 279 $build->create_build_script; 280 281This will find all F<.dat> files in the F<lib/> directory, copy them 282to the F<blib/lib/> directory during the C<build> action, and install 283them during the C<install> action. 284 285If your extra files aren't located in the C<lib/> directory in your 286distribution, you can explicitly say where they are, just as you'd do 287with F<.pm> or F<.pod> files: 288 289 use Module::Build; 290 my $build = new Module::Build 291 ( 292 module_name => 'Foo::Bar', 293 dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'}, 294 ...other stuff here... 295 ); 296 $build->add_build_element('dat'); 297 $build->create_build_script; 298 299If your extra files actually need to be created on the user's machine, 300or if they need some other kind of special processing, you'll probably 301want to subclass C<Module::Build> and create a special method to 302process them, named C<process_${kind}_files()>: 303 304 use Module::Build; 305 my $class = Module::Build->subclass(code => <<'EOF'); 306 sub process_dat_files { 307 my $self = shift; 308 ... locate and process *.dat files, 309 ... and create something in blib/lib/ 310 } 311 EOF 312 my $build = $class->new 313 ( 314 module_name => 'Foo::Bar', 315 ...other stuff here... 316 ); 317 $build->add_build_element('dat'); 318 $build->create_build_script; 319 320If your extra files don't go in F<lib/> but in some other place, see 321L<"Adding new elements to the install process"> for how to actually 322get them installed. 323 324Please note that these examples use some capabilities of Module::Build 325that first appeared in version 0.26. Before that it could 326still be done, but the simple cases took a bit more work. 327 328 329=head2 Adding new elements to the install process 330 331By default, Module::Build creates seven subdirectories of the F<blib> 332directory during the build process: F<lib>, F<arch>, F<bin>, 333F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be 334missing or empty if there's nothing to go in them). Anything copied 335to these directories during the build will eventually be installed 336during the C<install> action (see L<Module::Build/"INSTALL PATHS">. 337 338If you need to create a new custom type of installable element, e.g. C<conf>, 339then you need to tell Module::Build where things in F<blib/conf/> 340should be installed. To do this, use the C<install_path> parameter to 341the C<new()> method: 342 343 my $build = Module::Build->new 344 ( 345 ...other stuff here... 346 install_path => { conf => $installation_path } 347 ); 348 349Or you can call the C<install_path()> method later: 350 351 $build->install_path(conf => $installation_path); 352 353The user may also specify the path on the command line: 354 355 perl Build.PL --install_path conf=/foo/path/etc 356 357The important part, though, is that I<somehow> the install path needs 358to be set, or else nothing in the F<blib/conf/> directory will get 359installed, and a runtime error during the C<install> action will 360result. 361 362See also L<"Adding new file types to the build process"> for how to 363create the stuff in F<blib/conf/> in the first place. 364 365 366=head1 EXAMPLES ON CPAN 367 368Several distributions on CPAN are making good use of various features 369of Module::Build. They can serve as real-world examples for others. 370 371 372=head2 SVN-Notify-Mirror 373 374L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/> 375 376John Peacock, author of the C<SVN-Notify-Mirror> distribution, says: 377 378=over 4 379 380=item 1. Using C<auto_features>, I check to see whether two optional 381modules are available - SVN::Notify::Config and Net::SSH; 382 383=item 2. If the S::N::Config module is loaded, I automatically 384generate test files for it during Build (using the C<PL_files> 385property). 386 387=item 3. If the C<ssh_feature> is available, I ask if the user wishes 388to perform the ssh tests (since it requires a little preliminary 389setup); 390 391=item 4. Only if the user has C<ssh_feature> and answers yes to the 392testing, do I generate a test file. 393 394I'm sure I could not have handled this complexity with EU::MM, but it 395was very easy to do with M::B. 396 397=back 398 399 400=head2 Modifying an action 401 402Sometimes you might need an to have an action, say C<./Build install>, 403do something unusual. For instance, you might need to change the 404ownership of a file or do something else peculiar to your application. 405 406You can subclass C<Module::Build> on the fly using the C<subclass()> 407method and override the methods that perform the actions. You may 408need to read through C<Module::Build::Authoring> and 409C<Module::Build::API> to find the methods you want to override. All 410"action" methods are implemented by a method called "ACTION_" followed 411by the action's name, so here's an example of how it would work for 412the C<install> action: 413 414 # Build.PL 415 use Module::Build; 416 my $class = Module::Build->subclass( 417 class => "Module::Build::Custom", 418 code => <<'SUBCLASS' ); 419 420 sub ACTION_install { 421 my $self = shift; 422 # YOUR CODE HERE 423 $self->SUPER::ACTION_install; 424 } 425 SUBCLASS 426 427 $class->new( 428 module_name => 'Your::Module', 429 # rest of the usual Module::Build parameters 430 )->create_build_script; 431 432 433=head2 Adding an action 434 435You can add a new C<./Build> action simply by writing the method for 436it in your subclass. Use C<depends_on> to declare that another action 437must have been run before your action. 438 439For example, let's say you wanted to be able to write C<./Build 440commit> to test your code and commit it to Subversion. 441 442 # Build.PL 443 use Module::Build; 444 my $class = Module::Build->subclass( 445 class => "Module::Build::Custom", 446 code => <<'SUBCLASS' ); 447 448 sub ACTION_commit { 449 my $self = shift; 450 451 $self->depends_on("test"); 452 $self->do_system(qw(svn commit)); 453 } 454 SUBCLASS 455 456 457=head2 Bundling Module::Build 458 459Note: This section probably needs an update as the technology improves 460(see contrib/bundle.pl in the distribution). 461 462Suppose you want to use some new-ish features of Module::Build, 463e.g. newer than the version of Module::Build your users are likely to 464already have installed on their systems. The first thing you should 465do is set C<configure_requires> to your minimum version of 466Module::Build. See L<Module::Build::Authoring>. 467 468But not every build system honors C<configure_requires> yet. Here's 469how you can ship a copy of Module::Build, but still use a newer 470installed version to take advantage of any bug fixes and upgrades. 471 472First, install Module::Build into F<Your-Project/inc/Module-Build>. 473CPAN will not index anything in the F<inc> directory so this copy will 474not show up in CPAN searches. 475 476 cd Module-Build 477 perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build 478 ./Build test 479 ./Build install 480 481You should now have all the Module::Build .pm files in 482F<Your-Project/inc/Module-Build/lib/perl5>. 483 484Next, add this to the top of your F<Build.PL>. 485 486 my $Bundled_MB = 0.30; # or whatever version it was. 487 488 # Find out what version of Module::Build is installed or fail quietly. 489 # This should be cross-platform. 490 my $Installed_MB = 491 `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1"; 492 493 # some operating systems put a newline at the end of every print. 494 chomp $Installed_MB; 495 496 $Installed_MB = 0 if $?; 497 498 # Use our bundled copy of Module::Build if it's newer than the installed. 499 unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB; 500 501 require Module::Build; 502 503And write the rest of your F<Build.PL> normally. Module::Build will 504remember your change to C<@INC> and use it when you run F<./Build>. 505 506In the future, we hope to provide a more automated solution for this 507scenario; see C<inc/latest.pm> in the Module::Build distribution for 508one indication of the direction we're moving. 509 510 511=head1 AUTHOR 512 513Ken Williams <kwilliams@cpan.org> 514 515 516=head1 COPYRIGHT 517 518Copyright (c) 2001-2008 Ken Williams. All rights reserved. 519 520This library is free software; you can redistribute it and/or 521modify it under the same terms as Perl itself. 522 523 524=head1 SEE ALSO 525 526perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3), 527L<Module::Build::API>(3) 528 529=cut 530