home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / Cookbook.pm < prev    next >
Encoding:
Perl POD Document  |  2003-12-23  |  3.5 KB  |  120 lines
  1. package Module::Build::Cookbook;
  2.  
  3. =head1 NAME
  4.  
  5. Module::Build::Cookbook - Examples of Module::Build Usage
  6.  
  7. =head1 DESCRIPTION
  8.  
  9. C<Module::Build> isn't conceptually very complicated, but examples are
  10. always helpful.  I got the idea for writing this cookbook when
  11. attending Brian Ingerson's "Extreme Programming Tools for Module
  12. Authors" presentation at YAPC 2003, when he said, straightforwardly,
  13. "Write A Cookbook."
  14.  
  15. The definitional of how stuff works is in the main C<Module::Build>
  16. documentation.  It's best to get familiar with that too.
  17.  
  18. =head1 BASIC RECIPES
  19.  
  20. =head2 The basic installation recipe for modules that use Module::Build
  21.  
  22. In most cases, you can just issue the following commands from your
  23. shell:
  24.  
  25.  perl Build.PL
  26.  Build
  27.  Build test
  28.  Build install
  29.  
  30. There's nothing complicated here - first you're running a script
  31. called F<Build.PL>, then you're running a (newly-generated) script
  32. called F<Build> and passing it various arguments.  If you know how to
  33. do that on your system, you can get installation working.
  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. The F<Build> script knows what perl was used to run C<Build.PL>, so
  46. you don't need to reinvoke the F<Build> script with the complete perl
  47. path each time.  If you invoke it with the I<wrong> perl path, you'll
  48. get a warning.
  49.  
  50. If the current directory (usually called '.') isn't in your path, you
  51. can do C<./Build> or C<perl Build> to run the script:
  52.  
  53.  /usr/bin/perl Build.PL
  54.  ./Build
  55.  ./Build test
  56.  ./Build install
  57.  
  58. =head2 Making a CPAN.pm-compatible distribution
  59.  
  60. New versions of CPAN.pm understand how to use a F<Build.PL> script,
  61. but old versions don't.  If you want to help users who have old
  62. versions, do the following:
  63.  
  64. Create a file in your distribution named F<Makefile.PL>, with the
  65. following contents:  
  66.  
  67.  use Module::Build::Compat;
  68.  Module::Build::Compat->run_build_pl(args => \@ARGV);
  69.  Module::Build::Compat->write_makefile();
  70.  
  71. Now CPAN will work as usual, ie: `perl Makefile.PL`, `make`, `make test`,
  72. and `make install`.
  73.  
  74. Alternatively, see the C<create_makefile_pl> parameter to the C<<
  75. Module::Build->new() >> method.
  76.  
  77. =head2 Installing modules using the programmatic interface
  78.  
  79. If you need to build, test, and/or install modules from within some
  80. other perl code (as opposed to having the user type installation
  81. commands at the shell), you can use the programmatic interface.
  82. Create a Module::Build object (or an object of a custom Module::Build
  83. subclass) and then invoke its C<dispatch()> method to run various
  84. actions.
  85.  
  86.  my $b = Module::Build->new(
  87.    module_name => 'Foo::Bar',
  88.    license => 'perl',
  89.    requires => { 'Some::Module'   => '1.23' },
  90.  );
  91.  $b->dispatch('build');
  92.  $b->dispatch('test', verbose => 1);
  93.  $b->dispatch('install);
  94.  
  95. The first argument to C<dispatch()> is the name of the action, and any
  96. following arguments are named parameters.
  97.  
  98. This is the interface we use to test Module::Build itself in the
  99. regression tests.
  100.  
  101. =head2 Installing to a temporary directory
  102.  
  103. To create packages for package managers like RedHat's C<rpm> or
  104. Debian's C<deb>, you may need to install to a temporary directory
  105. first and then create the package from that temporary installation.
  106. To do this, specify the C<destdir> parameter to the C<install> action:
  107.  
  108.  Build install destdir=/tmp/my-package-1.003
  109.  
  110.  
  111. =head1 AUTHOR
  112.  
  113. Ken Williams, ken@mathforum.org
  114.  
  115. =head1 SEE ALSO
  116.  
  117. perl(1), Module::Build(3)
  118.  
  119. =cut
  120.