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 There are three basic types of prerequisites that can be defined: 1)
 145 "requires" - are versions of modules that are required for certain
 146 functionality to be available; 2) "recommends" - are versions of
 147 modules that are recommended to provide enhanced functionality; and 3)
 148 "conflicts" - are versions of modules that conflict with, and that can
 149 cause problems with the distribution.
 150
 151 Each of the three types of prerequisites listed above can be applied
 152 to different aspects of the Build process.  For the module distribution
 153 itself you simply define "requires", "recommends", or "conflicts".  The
 154 types can also apply to other aspects of the Build process.  Currently,
 155 only "build_requires" is defined which is used for modules which are
 156 required during the Build process.
 157
 158
 159 =head2 Format of prerequisites
 160
 161 The prerequisites are given in a hash reference, where the keys are
 162 the module names and the values are version specifiers:
 163
 164   requires => {
 165                Foo::Module => '2.4',
 166                Bar::Module => 0,
 167                Ken::Module => '>= 1.2, != 1.5, < 2.0',
 168                perl => '5.6.0'
 169               },
 170
 171 These four version specifiers have different effects.  The value
 172 C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
 173 installed.  The value C<0> means that B<any> version of C<Bar::Module>
 174 is acceptable, even if C<Bar::Module> doesn't define a version.  The
 175 more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
 176 C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
 177 and B<not equal to> 1.5.  The list of criteria is separated by commas,
 178 and all criteria must be satisfied.
 179
 180 A special C<perl> entry lets you specify the versions of the Perl
 181 interpreter that are supported by your module.  The same version
 182 dependency-checking semantics are available, except that we also
 183 understand perl's new double-dotted version numbers.
 184
 185
 186 =head1 SAVING CONFIGURATION INFORMATION
 187
 188 Module::Build provides a very convenient way to save configuration
 189 information that your installed modules (or your regression tests) can
 190 access.  If your Build process calls the C<feature()> or
 191 C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
 192 automatically be created for you, where C<Foo::Bar> is the
 193 C<module_name> parameter as passed to C<new()>.  This module provides
 194 access to the data saved by these methods, and a way to update the
 195 values.  There is also a utility script called C<config_data>
 196 distributed with Module::Build that provides a command line interface
 197 to this same functionality.  See also the generated
 198 C<Foo::Bar::ConfigData> documentation, and the C<config_data>
 199 script's documentation, for more information.
 200
 201
 202 =head1 STARTING MODULE DEVELOPMENT
 203
 204 When starting development on a new module, it's rarely worth your time
 205 to create a tree of all the files by hand.  Some automatic
 206 module-creators are available: the oldest is C<h2xs>, which has
 207 shipped with perl itself for a long time.  Its name reflects the fact
 208 that modules were originally conceived of as a way to wrap up a C
 209 library (thus the C<h> part) into perl extensions (thus the C<xs>
 210 part).
 211
 212 These days, C<h2xs> has largely been superseded by modules like
 213 C<ExtUtils::ModuleMaker>, C<Module::Starter>, and C<Module::Maker>.
 214 They have varying degrees of support for C<Module::Build>.
 215
 216
 217 =head1 AUTOMATION
 218
 219 One advantage of Module::Build is that since it's implemented as Perl
 220 methods, you can invoke these methods directly if you want to install
 221 a module non-interactively.  For instance, the following Perl script
 222 will invoke the entire build/install procedure:
 223
 224   my $build = Module::Build->new(module_name => 'MyModule');
 225   $build->dispatch('build');
 226   $build->dispatch('test');
 227   $build->dispatch('install');
 228
 229 If any of these steps encounters an error, it will throw a fatal
 230 exception.
 231
 232 You can also pass arguments as part of the build process:
 233
 234   my $build = Module::Build->new(module_name => 'MyModule');
 235   $build->dispatch('build');
 236   $build->dispatch('test', verbose => 1);
 237   $build->dispatch('install', sitelib => '/my/secret/place/');
 238
 239 Building and installing modules in this way skips creating the
 240 C<Build> script.
 241
 242
 243 =head1 MIGRATION
 244
 245 Note that if you want to provide both a F<Makefile.PL> and a
 246 F<Build.PL> for your distribution, you probably want to add the
 247 following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker
 248 doesn't try to run your F<Build.PL> as a normal F<.PL> file:
 249
 250   PL_FILES => {},
 251
 252 You may also be interested in looking at the C<Module::Build::Compat>
 253 module, which can automatically create various kinds of F<Makefile.PL>
 254 compatibility layers.
 255
 256
 257 =head1 AUTHOR
 258
 259 Ken Williams <kwilliams@cpan.org>
 260
 261 Development questions, bug reports, and patches should be sent to the
 262 Module-Build mailing list at <module-build@perl.org>.
 263
 264 Bug reports are also welcome at
 265 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
 266
 267 The latest development version is available from the Subversion
 268 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
 269
 270
 271 =head1 SEE ALSO
 272
 273 perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
 274 L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
 275
 276 F<META.yml> Specification:
 277 L<http://module-build.sourceforge.net/META-spec-current.html>
 278
 279 L<http://www.dsmit.com/cons/>
 280
 281 L<http://search.cpan.org/dist/PerlBuildSystem/>
 282
 283 =cut