lib/Module/Build/Authoring.pod

   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