| 1 | package Module::Build::Cookbook; |
| 2 | use strict; |
| 3 | use vars qw($VERSION); |
| 4 | $VERSION = '0.4008'; |
| 5 | |
| 6 | |
| 7 | =head1 NAME |
| 8 | |
| 9 | Module::Build::Cookbook - Examples of Module::Build Usage |
| 10 | |
| 11 | =head1 DESCRIPTION |
| 12 | |
| 13 | C<Module::Build> isn't conceptually very complicated, but examples are |
| 14 | always helpful. The following recipes should help developers and/or |
| 15 | installers put together the pieces from the other parts of the |
| 16 | documentation. |
| 17 | |
| 18 | |
| 19 | =head1 BASIC RECIPES |
| 20 | |
| 21 | |
| 22 | =head2 Installing modules that use Module::Build |
| 23 | |
| 24 | In most cases, you can just issue the following commands: |
| 25 | |
| 26 | perl Build.PL |
| 27 | ./Build |
| 28 | ./Build test |
| 29 | ./Build install |
| 30 | |
| 31 | There's nothing complicated here - first you're running a script |
| 32 | called F<Build.PL>, then you're running a (newly-generated) script |
| 33 | called F<Build> and passing it various arguments. |
| 34 | |
| 35 | The exact commands may vary a bit depending on how you invoke perl |
| 36 | scripts on your system. For instance, if you have multiple versions |
| 37 | of perl installed, you can install to one particular perl's library |
| 38 | directories like so: |
| 39 | |
| 40 | /usr/bin/perl5.8.1 Build.PL |
| 41 | ./Build |
| 42 | ./Build test |
| 43 | ./Build install |
| 44 | |
| 45 | If you're on Windows where the current directory is always searched |
| 46 | first for scripts, you'll probably do something like this: |
| 47 | |
| 48 | perl Build.PL |
| 49 | Build |
| 50 | Build test |
| 51 | Build install |
| 52 | |
| 53 | On the old Mac OS (version 9 or lower) using MacPerl, you can |
| 54 | double-click on the F<Build.PL> script to create the F<Build> script, |
| 55 | then double-click on the F<Build> script to run its C<build>, C<test>, |
| 56 | and C<install> actions. |
| 57 | |
| 58 | The F<Build> script knows what perl was used to run F<Build.PL>, so |
| 59 | you don't need to re-invoke the F<Build> script with the complete perl |
| 60 | path each time. If you invoke it with the I<wrong> perl path, you'll |
| 61 | get a warning or a fatal error. |
| 62 | |
| 63 | =head2 Modifying Config.pm values |
| 64 | |
| 65 | C<Module::Build> relies heavily on various values from perl's |
| 66 | C<Config.pm> to do its work. For example, default installation paths |
| 67 | are given by C<installsitelib> and C<installvendorman3dir> and |
| 68 | friends, C linker & compiler settings are given by C<ld>, |
| 69 | C<lddlflags>, C<cc>, C<ccflags>, and so on. I<If you're pretty sure |
| 70 | you know what you're doing>, you can tell C<Module::Build> to pretend |
| 71 | there are different values in F<Config.pm> than what's really there, |
| 72 | by passing arguments for the C<--config> parameter on the command |
| 73 | line: |
| 74 | |
| 75 | perl Build.PL --config cc=gcc --config ld=gcc |
| 76 | |
| 77 | Inside the C<Build.PL> script the same thing can be accomplished by |
| 78 | passing 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 | |
| 87 | In custom build code, the same thing can be accomplished by calling |
| 88 | the 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 | |
| 98 | If you need to build, test, and/or install modules from within some |
| 99 | other perl code (as opposed to having the user type installation |
| 100 | commands at the shell), you can use the programmatic interface. |
| 101 | Create a Module::Build object (or an object of a custom Module::Build |
| 102 | subclass) and then invoke its C<dispatch()> method to run various |
| 103 | actions. |
| 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 | |
| 115 | The first argument to C<dispatch()> is the name of the action, and any |
| 116 | following arguments are named parameters. |
| 117 | |
| 118 | This is the interface we use to test Module::Build itself in the |
| 119 | regression tests. |
| 120 | |
| 121 | |
| 122 | =head2 Installing to a temporary directory |
| 123 | |
| 124 | To create packages for package managers like RedHat's C<rpm> or |
| 125 | Debian's C<deb>, you may need to install to a temporary directory |
| 126 | first and then create the package from that temporary installation. |
| 127 | To do this, specify the C<destdir> parameter to the C<install> action: |
| 128 | |
| 129 | ./Build install --destdir /tmp/my-package-1.003 |
| 130 | |
| 131 | This essentially just prepends all the installation paths with the |
| 132 | F</tmp/my-package-1.003> directory. |
| 133 | |
| 134 | |
| 135 | =head2 Installing to a non-standard directory |
| 136 | |
| 137 | To install to a non-standard directory (for example, if you don't have |
| 138 | permission to install in the system-wide directories), you can use the |
| 139 | C<install_base> or C<prefix> parameters: |
| 140 | |
| 141 | ./Build install --install_base /foo/bar |
| 142 | |
| 143 | See L<Module::Build/"INSTALL PATHS"> for a much more complete |
| 144 | discussion of how installation paths are determined. |
| 145 | |
| 146 | |
| 147 | =head2 Installing in the same location as ExtUtils::MakeMaker |
| 148 | |
| 149 | With the introduction of C<--prefix> in Module::Build 0.28 and |
| 150 | C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both |
| 151 | to install to the same locations. |
| 152 | |
| 153 | First, ensure you have at least version 0.28 of Module::Build |
| 154 | installed and 6.31 of C<ExtUtils::MakeMaker>. Prior versions have |
| 155 | differing (and in some cases quite strange) installation behaviors. |
| 156 | |
| 157 | The following installation flags are equivalent between |
| 158 | C<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 | |
| 171 | For example, if you are currently installing C<MakeMaker> modules with |
| 172 | this command: |
| 173 | |
| 174 | perl Makefile.PL PREFIX=~ |
| 175 | make test |
| 176 | make install UNINST=1 |
| 177 | |
| 178 | You 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 | |
| 186 | The behavior of C<prefix> is complicated and depends on |
| 187 | how your Perl is configured. The resulting installation locations |
| 188 | will vary from machine to machine and even different installations of |
| 189 | Perl on the same machine. Because of this, it's difficult to document |
| 190 | where C<prefix> will place your modules. |
| 191 | |
| 192 | In contrast, C<install_base> has predictable, easy to explain |
| 193 | installation locations. Now that C<Module::Build> and C<MakeMaker> both |
| 194 | have C<install_base> there is little reason to use C<prefix> other |
| 195 | than to preserve your existing installation locations. If you are |
| 196 | starting a fresh Perl installation we encourage you to use |
| 197 | C<install_base>. If you have an existing installation installed via |
| 198 | C<prefix>, consider moving it to an installation structure matching |
| 199 | C<install_base> and using that instead. |
| 200 | |
| 201 | |
| 202 | =head2 Running a single test file |
| 203 | |
| 204 | C<Module::Build> supports running a single test, which enables you to |
| 205 | track down errors more quickly. Use the following format: |
| 206 | |
| 207 | ./Build test --test_files t/mytest.t |
| 208 | |
| 209 | In addition, you may want to run the test in verbose mode to get more |
| 210 | informative output: |
| 211 | |
| 212 | ./Build test --test_files t/mytest.t --verbose 1 |
| 213 | |
| 214 | I run this so frequently that I define the following shell alias: |
| 215 | |
| 216 | alias t './Build test --verbose 1 --test_files' |
| 217 | |
| 218 | So 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 | |
| 226 | New versions of CPAN.pm understand how to use a F<Build.PL> script, |
| 227 | but old versions don't. If authors want to help users who have old |
| 228 | versions, some form of F<Makefile.PL> should be supplied. The easiest |
| 229 | way to accomplish this is to use the C<create_makefile_pl> parameter to |
| 230 | C<< Module::Build->new() >> in the C<Build.PL> script, which can |
| 231 | create various flavors of F<Makefile.PL> during the C<dist> action. |
| 232 | |
| 233 | As a best practice, we recommend using the "traditional" style of |
| 234 | F<Makefile.PL> unless your distribution has needs that can't be |
| 235 | accomplished that way. |
| 236 | |
| 237 | The C<Module::Build::Compat> module, which is part of |
| 238 | C<Module::Build>'s distribution, is responsible for creating these |
| 239 | F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details. |
| 240 | |
| 241 | |
| 242 | =head2 Changing the order of the build process |
| 243 | |
| 244 | The C<build_elements> property specifies the steps C<Module::Build> |
| 245 | will take when building a distribution. To change the build order, |
| 246 | change 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 | |
| 253 | Currently, C<build_elements> has the following default value: |
| 254 | |
| 255 | [qw( PL support pm xs pod script )] |
| 256 | |
| 257 | Do take care when altering this property, since there may be |
| 258 | non-obvious (and non-documented!) ordering dependencies in the |
| 259 | C<Module::Build> code. |
| 260 | |
| 261 | |
| 262 | =head2 Adding new file types to the build process |
| 263 | |
| 264 | Sometimes you might have extra types of files that you want to install |
| 265 | alongside the standard types like F<.pm> and F<.pod> files. For |
| 266 | instance, you might have a F<Bar.dat> file containing some data |
| 267 | related to the C<Foo::Bar> module and you'd like for it to end up as |
| 268 | F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can |
| 269 | access it easily at runtime. The following code from a sample |
| 270 | C<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 | |
| 281 | This will find all F<.dat> files in the F<lib/> directory, copy them |
| 282 | to the F<blib/lib/> directory during the C<build> action, and install |
| 283 | them during the C<install> action. |
| 284 | |
| 285 | If your extra files aren't located in the C<lib/> directory in your |
| 286 | distribution, you can explicitly say where they are, just as you'd do |
| 287 | with 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 | |
| 299 | If your extra files actually need to be created on the user's machine, |
| 300 | or if they need some other kind of special processing, you'll probably |
| 301 | want to subclass C<Module::Build> and create a special method to |
| 302 | process 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 | |
| 320 | If your extra files don't go in F<lib/> but in some other place, see |
| 321 | L<"Adding new elements to the install process"> for how to actually |
| 322 | get them installed. |
| 323 | |
| 324 | Please note that these examples use some capabilities of Module::Build |
| 325 | that first appeared in version 0.26. Before that it could |
| 326 | still be done, but the simple cases took a bit more work. |
| 327 | |
| 328 | |
| 329 | =head2 Adding new elements to the install process |
| 330 | |
| 331 | By default, Module::Build creates seven subdirectories of the F<blib> |
| 332 | directory during the build process: F<lib>, F<arch>, F<bin>, |
| 333 | F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be |
| 334 | missing or empty if there's nothing to go in them). Anything copied |
| 335 | to these directories during the build will eventually be installed |
| 336 | during the C<install> action (see L<Module::Build/"INSTALL PATHS">. |
| 337 | |
| 338 | If you need to create a new custom type of installable element, e.g. C<conf>, |
| 339 | then you need to tell Module::Build where things in F<blib/conf/> |
| 340 | should be installed. To do this, use the C<install_path> parameter to |
| 341 | the C<new()> method: |
| 342 | |
| 343 | my $build = Module::Build->new |
| 344 | ( |
| 345 | ...other stuff here... |
| 346 | install_path => { conf => $installation_path } |
| 347 | ); |
| 348 | |
| 349 | Or you can call the C<install_path()> method later: |
| 350 | |
| 351 | $build->install_path(conf => $installation_path); |
| 352 | |
| 353 | The user may also specify the path on the command line: |
| 354 | |
| 355 | perl Build.PL --install_path conf=/foo/path/etc |
| 356 | |
| 357 | The important part, though, is that I<somehow> the install path needs |
| 358 | to be set, or else nothing in the F<blib/conf/> directory will get |
| 359 | installed, and a runtime error during the C<install> action will |
| 360 | result. |
| 361 | |
| 362 | See also L<"Adding new file types to the build process"> for how to |
| 363 | create the stuff in F<blib/conf/> in the first place. |
| 364 | |
| 365 | |
| 366 | =head1 EXAMPLES ON CPAN |
| 367 | |
| 368 | Several distributions on CPAN are making good use of various features |
| 369 | of Module::Build. They can serve as real-world examples for others. |
| 370 | |
| 371 | |
| 372 | =head2 SVN-Notify-Mirror |
| 373 | |
| 374 | L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/> |
| 375 | |
| 376 | John 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 |
| 381 | modules are available - SVN::Notify::Config and Net::SSH; |
| 382 | |
| 383 | =item 2. If the S::N::Config module is loaded, I automatically |
| 384 | generate test files for it during Build (using the C<PL_files> |
| 385 | property). |
| 386 | |
| 387 | =item 3. If the C<ssh_feature> is available, I ask if the user wishes |
| 388 | to perform the ssh tests (since it requires a little preliminary |
| 389 | setup); |
| 390 | |
| 391 | =item 4. Only if the user has C<ssh_feature> and answers yes to the |
| 392 | testing, do I generate a test file. |
| 393 | |
| 394 | I'm sure I could not have handled this complexity with EU::MM, but it |
| 395 | was very easy to do with M::B. |
| 396 | |
| 397 | =back |
| 398 | |
| 399 | |
| 400 | =head2 Modifying an action |
| 401 | |
| 402 | Sometimes you might need an to have an action, say C<./Build install>, |
| 403 | do something unusual. For instance, you might need to change the |
| 404 | ownership of a file or do something else peculiar to your application. |
| 405 | |
| 406 | You can subclass C<Module::Build> on the fly using the C<subclass()> |
| 407 | method and override the methods that perform the actions. You may |
| 408 | need to read through C<Module::Build::Authoring> and |
| 409 | C<Module::Build::API> to find the methods you want to override. All |
| 410 | "action" methods are implemented by a method called "ACTION_" followed |
| 411 | by the action's name, so here's an example of how it would work for |
| 412 | the 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 | |
| 435 | You can add a new C<./Build> action simply by writing the method for |
| 436 | it in your subclass. Use C<depends_on> to declare that another action |
| 437 | must have been run before your action. |
| 438 | |
| 439 | For example, let's say you wanted to be able to write C<./Build |
| 440 | commit> 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 | |
| 459 | Note: This section probably needs an update as the technology improves |
| 460 | (see contrib/bundle.pl in the distribution). |
| 461 | |
| 462 | Suppose you want to use some new-ish features of Module::Build, |
| 463 | e.g. newer than the version of Module::Build your users are likely to |
| 464 | already have installed on their systems. The first thing you should |
| 465 | do is set C<configure_requires> to your minimum version of |
| 466 | Module::Build. See L<Module::Build::Authoring>. |
| 467 | |
| 468 | But not every build system honors C<configure_requires> yet. Here's |
| 469 | how you can ship a copy of Module::Build, but still use a newer |
| 470 | installed version to take advantage of any bug fixes and upgrades. |
| 471 | |
| 472 | First, install Module::Build into F<Your-Project/inc/Module-Build>. |
| 473 | CPAN will not index anything in the F<inc> directory so this copy will |
| 474 | not 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 | |
| 481 | You should now have all the Module::Build .pm files in |
| 482 | F<Your-Project/inc/Module-Build/lib/perl5>. |
| 483 | |
| 484 | Next, 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 | |
| 503 | And write the rest of your F<Build.PL> normally. Module::Build will |
| 504 | remember your change to C<@INC> and use it when you run F<./Build>. |
| 505 | |
| 506 | In the future, we hope to provide a more automated solution for this |
| 507 | scenario; see C<inc/latest.pm> in the Module::Build distribution for |
| 508 | one indication of the direction we're moving. |
| 509 | |
| 510 | |
| 511 | =head1 AUTHOR |
| 512 | |
| 513 | Ken Williams <kwilliams@cpan.org> |
| 514 | |
| 515 | |
| 516 | =head1 COPYRIGHT |
| 517 | |
| 518 | Copyright (c) 2001-2008 Ken Williams. All rights reserved. |
| 519 | |
| 520 | This library is free software; you can redistribute it and/or |
| 521 | modify it under the same terms as Perl itself. |
| 522 | |
| 523 | |
| 524 | =head1 SEE ALSO |
| 525 | |
| 526 | perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3), |
| 527 | L<Module::Build::API>(3) |
| 528 | |
| 529 | =cut |