[ Index ] |
PHP Cross Reference of Unnamed Project |
[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
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |