[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  Module::Build::Authoring - Authoring Module::Build modules
   4  
   5  
   6  =head1 DESCRIPTION
   7  
   8  When creating a C<Build.PL> script for a module, something like the
   9  following code will typically be used:
  10  
  11    use Module::Build;
  12    my $build = Module::Build->new
  13      (
  14       module_name => 'Foo::Bar',
  15       license  => 'perl',
  16       requires => {
  17                    'perl'          => '5.6.1',
  18                    'Some::Module'  => '1.23',
  19                    'Other::Module' => '>= 1.2, != 1.5, < 2.0',
  20                   },
  21      );
  22    $build->create_build_script;
  23  
  24  A simple module could get away with something as short as this for its
  25  C<Build.PL> script:
  26  
  27    use Module::Build;
  28    Module::Build->new(
  29      module_name => 'Foo::Bar',
  30      license     => 'perl',
  31    )->create_build_script;
  32  
  33  The model used by C<Module::Build> is a lot like the C<MakeMaker>
  34  metaphor, with the following correspondences:
  35  
  36     In Module::Build                 In ExtUtils::MakeMaker
  37    ---------------------------      ------------------------
  38     Build.PL (initial script)        Makefile.PL (initial script)
  39     Build (a short perl script)      Makefile (a long Makefile)
  40     _build/ (saved state info)       various config text in the Makefile
  41  
  42  Any customization can be done simply by subclassing C<Module::Build>
  43  and adding a method called (for example) C<ACTION_test>, overriding
  44  the default 'test' action.  You could also add a method called
  45  C<ACTION_whatever>, and then you could perform the action C<Build
  46  whatever>.
  47  
  48  For information on providing compatibility with
  49  C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
  50  L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
  51  
  52  
  53  =head1 STRUCTURE
  54  
  55  Module::Build creates a class hierarchy conducive to customization.
  56  Here is the parent-child class hierarchy in classy ASCII art:
  57  
  58     /--------------------\
  59     |   Your::Parent     |  (If you subclass Module::Build)
  60     \--------------------/
  61              |
  62              |
  63     /--------------------\  (Doesn't define any functionality
  64     |   Module::Build    |   of its own - just figures out what
  65     \--------------------/   other modules to load.)
  66              |
  67              |
  68     /-----------------------------------\  (Some values of $^O may
  69     |   Module::Build::Platform::$^O    |   define specialized functionality.
  70     \-----------------------------------/   Otherwise it's ...::Default, a
  71              |                              pass-through class.)
  72              |
  73     /--------------------------\
  74     |   Module::Build::Base    |  (Most of the functionality of 
  75     \--------------------------/   Module::Build is defined here.)
  76  
  77  
  78  =head1 SUBCLASSING
  79  
  80  Right now, there are two ways to subclass Module::Build.  The first
  81  way is to create a regular module (in a C<.pm> file) that inherits
  82  from Module::Build, and use that module's class instead of using
  83  Module::Build directly:
  84  
  85    ------ in Build.PL: ----------
  86    #!/usr/bin/perl
  87  
  88    use lib q(/nonstandard/library/path);
  89    use My::Builder;  # Or whatever you want to call it
  90  
  91    my $build = My::Builder->new
  92      (
  93       module_name => 'Foo::Bar',  # All the regular args...
  94       license     => 'perl',
  95       dist_author => 'A N Other <me@here.net.au>',
  96       requires    => { Carp => 0 }
  97      );
  98    $build->create_build_script;
  99  
 100  This is relatively straightforward, and is the best way to do things
 101  if your My::Builder class contains lots of code.  The
 102  C<create_build_script()> method will ensure that the current value of
 103  C<@INC> (including the C</nonstandard/library/path>) is propogated to
 104  the Build script, so that My::Builder can be found when running build
 105  actions.
 106  
 107  For very small additions, Module::Build provides a C<subclass()>
 108  method that lets you subclass Module::Build more conveniently, without
 109  creating a separate file for your module:
 110  
 111    ------ in Build.PL: ----------
 112    #!/usr/bin/perl
 113  
 114    use Module::Build;
 115    my $class = Module::Build->subclass
 116      (
 117       class => 'My::Builder',
 118       code => q{
 119         sub ACTION_foo {
 120           print "I'm fooing to death!\n";
 121         }
 122       },
 123      );
 124  
 125    my $build = $class->new
 126      (
 127       module_name => 'Foo::Bar',  # All the regular args...
 128       license     => 'perl',
 129       dist_author => 'A N Other <me@here.net.au>',
 130       requires    => { Carp => 0 }
 131      );
 132    $build->create_build_script;
 133  
 134  Behind the scenes, this actually does create a C<.pm> file, since the
 135  code you provide must persist after Build.PL is run if it is to be
 136  very useful.
 137  
 138  See also the documentation for the L<Module::Build::API/"subclass()">
 139  method.
 140  
 141  
 142  =head1 PREREQUISITES
 143  
 144  =head2 Types of prerequisites
 145  
 146  To specify what versions of other modules are used by this
 147  distribution, several types of prerequisites can be defined with the
 148  following parameters:
 149  
 150  =over 3
 151  
 152  =item configure_requires
 153  
 154  Items that must be installed I<before> configuring this distribution
 155  (i.e. before running the F<Build.PL> script).  This might be a
 156  specific minimum version of C<Module::Build> or any other module the
 157  F<Build.PL> needs in order to do its stuff.  Clients like C<CPAN.pm>
 158  or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
 159  F<META.yml> file and install these items before running the
 160  C<Build.PL>.
 161  
 162  *TODO* auto-add M::B?  In what circumstances?
 163  
 164  =item build_requires
 165  
 166  Items that are necessary for building and testing this distribution,
 167  but aren't necessary after installation.  This can help users who only
 168  want to install these items temporarily.  It also helps reduce the
 169  size of the CPAN dependency graph if everything isn't smooshed into
 170  C<requires>.
 171  
 172  =item requires
 173  
 174  Items that are necessary for basic functioning.
 175  
 176  =item recommends
 177  
 178  Items that are recommended for enhanced functionality, but there are
 179  ways to use this distribution without having them installed.  You
 180  might also think of this as "can use" or "is aware of" or "changes
 181  behavior in the presence of".
 182  
 183  =item conflicts
 184  
 185  Items that can cause problems with this distribution when installed.
 186  This is pretty rare.
 187  
 188  =back
 189  
 190  =head2 Format of prerequisites
 191  
 192  The prerequisites are given in a hash reference, where the keys are
 193  the module names and the values are version specifiers:
 194  
 195    requires => {
 196                 Foo::Module => '2.4',
 197                 Bar::Module => 0,
 198                 Ken::Module => '>= 1.2, != 1.5, < 2.0',
 199                 perl => '5.6.0'
 200                },
 201  
 202  The above four version specifiers have different effects.  The value
 203  C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
 204  installed.  The value C<0> means that B<any> version of C<Bar::Module>
 205  is acceptable, even if C<Bar::Module> doesn't define a version.  The
 206  more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
 207  C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
 208  and B<not equal to> 1.5.  The list of criteria is separated by commas,
 209  and all criteria must be satisfied.
 210  
 211  A special C<perl> entry lets you specify the versions of the Perl
 212  interpreter that are supported by your module.  The same version
 213  dependency-checking semantics are available, except that we also
 214  understand perl's new double-dotted version numbers.
 215  
 216  =head2 XS Extensions
 217  
 218  Modules which need to compile XS code should list C<ExtUtils::CBuilder>
 219  as a C<build_requires> element.
 220  
 221  
 222  =head1 SAVING CONFIGURATION INFORMATION
 223  
 224  Module::Build provides a very convenient way to save configuration
 225  information that your installed modules (or your regression tests) can
 226  access.  If your Build process calls the C<feature()> or
 227  C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
 228  automatically be created for you, where C<Foo::Bar> is the
 229  C<module_name> parameter as passed to C<new()>.  This module provides
 230  access to the data saved by these methods, and a way to update the
 231  values.  There is also a utility script called C<config_data>
 232  distributed with Module::Build that provides a command line interface
 233  to this same functionality.  See also the generated
 234  C<Foo::Bar::ConfigData> documentation, and the C<config_data>
 235  script's documentation, for more information.
 236  
 237  
 238  =head1 STARTING MODULE DEVELOPMENT
 239  
 240  When starting development on a new module, it's rarely worth your time
 241  to create a tree of all the files by hand.  Some automatic
 242  module-creators are available: the oldest is C<h2xs>, which has
 243  shipped with perl itself for a long time.  Its name reflects the fact
 244  that modules were originally conceived of as a way to wrap up a C
 245  library (thus the C<h> part) into perl extensions (thus the C<xs>
 246  part).
 247  
 248  These days, C<h2xs> has largely been superseded by modules like
 249  C<ExtUtils::ModuleMaker>, and C<Module::Starter>.  They have varying
 250  degrees of support for C<Module::Build>.
 251  
 252  
 253  =head1 AUTOMATION
 254  
 255  One advantage of Module::Build is that since it's implemented as Perl
 256  methods, you can invoke these methods directly if you want to install
 257  a module non-interactively.  For instance, the following Perl script
 258  will invoke the entire build/install procedure:
 259  
 260    my $build = Module::Build->new(module_name => 'MyModule');
 261    $build->dispatch('build');
 262    $build->dispatch('test');
 263    $build->dispatch('install');
 264  
 265  If any of these steps encounters an error, it will throw a fatal
 266  exception.
 267  
 268  You can also pass arguments as part of the build process:
 269  
 270    my $build = Module::Build->new(module_name => 'MyModule');
 271    $build->dispatch('build');
 272    $build->dispatch('test', verbose => 1);
 273    $build->dispatch('install', sitelib => '/my/secret/place/');
 274  
 275  Building and installing modules in this way skips creating the
 276  C<Build> script.
 277  
 278  
 279  =head1 MIGRATION
 280  
 281  Note that if you want to provide both a F<Makefile.PL> and a
 282  F<Build.PL> for your distribution, you probably want to add the
 283  following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker
 284  doesn't try to run your F<Build.PL> as a normal F<.PL> file:
 285  
 286    PL_FILES => {},
 287  
 288  You may also be interested in looking at the C<Module::Build::Compat>
 289  module, which can automatically create various kinds of F<Makefile.PL>
 290  compatibility layers.
 291  
 292  
 293  =head1 AUTHOR
 294  
 295  Ken Williams <kwilliams@cpan.org>
 296  
 297  Development questions, bug reports, and patches should be sent to the
 298  Module-Build mailing list at <module-build@perl.org>.
 299  
 300  Bug reports are also welcome at
 301  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
 302  
 303  The latest development version is available from the Subversion
 304  repository at <https://svn.perl.org/modules/Module-Build/trunk/>
 305  
 306  
 307  =head1 SEE ALSO
 308  
 309  perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
 310  L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
 311  
 312  F<META.yml> Specification:
 313  L<http://module-build.sourceforge.net/META-spec-current.html>
 314  
 315  L<http://www.dsmit.com/cons/>
 316  
 317  L<http://search.cpan.org/dist/PerlBuildSystem/>
 318  
 319  =cut