[Summary view] [Print] [Text view]

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