[Module-build-checkins] Module-Build/lib/Module/Build Authoring.pod,1.26,1.27 Base.pm,1.533,1.534 Co
Status: Beta
Brought to you by:
kwilliams
Menu
▾
▴
[Module-build-checkins] Module-Build/lib/Module/Build Authoring.pod,1.26,1.27 Base.pm,1.533,1.534 Compat.pm,1.71,1.72 Cookbook.pm,1.17,1.18 ModuleInfo.pm,1.14,1.15 Notes.pm,1.8,1.9 PPMMaker.pm,1.10,1.11 PodParser.pm,1.7,1.8
Update of /cvsroot/module-build/Module-Build/lib/Module/Build In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv32185/lib/Module/Build Modified Files: Authoring.pod Base.pm Compat.pm Cookbook.pm ModuleInfo.pm Notes.pm PPMMaker.pm PodParser.pm Log Message: Move some code examples from the Module::Build module documentation to Module::Build::Authoring. Attempt to add more consistency across all documents (while trying to maintain Ken's style): * Use consistent two space indentation for verbatim paragraphs. * Add some consistency to example code: variable & module names; indentation; etc * Use consistent commandline syntax: "./Build" rather than "perl Build" or "Build"; and use long option style for most options. * Use standard quoting for various URI, email addresses. * Misc. pod formatting. Index: PPMMaker.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/PPMMaker.pm,v retrieving revision 1.10 retrieving revision 1.11 diff -u -d -r1.10 -r1.11 --- PPMMaker.pm 17 Apr 2005 03:38:29 -0000 1.10 +++ PPMMaker.pm 2 Dec 2005 12:12:21 -0000 1.11 @@ -151,14 +151,17 @@ 1; __END__ + =head1 NAME Module::Build::PPMMaker - Perl Package Manager file creation + =head1 SYNOPSIS - On the command line, builds a .ppd file: - % ./Build ppd + On the command line, builds a .ppd file: + ./Build ppd + =head1 DESCRIPTION @@ -167,10 +170,12 @@ Manager". Details are here: L<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/> + =head1 AUTHOR Dave Rolsky <au...@ur...>, Ken Williams <ke...@ma...> + =head1 COPYRIGHT Copyright (c) 2001-2005 Ken Williams. All rights reserved. @@ -178,6 +183,7 @@ This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. + =head1 SEE ALSO perl(1), Module::Build(3) Index: Compat.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Compat.pm,v retrieving revision 1.71 retrieving revision 1.72 diff -u -d -r1.71 -r1.72 --- Compat.pm 1 Dec 2005 02:11:06 -0000 1.71 +++ Compat.pm 2 Dec 2005 12:12:21 -0000 1.72 @@ -273,15 +273,17 @@ Module::Build::Compat - Compatibility with ExtUtils::MakeMaker + =head1 SYNOPSIS - # In a Build.PL : - use Module::Build; - my $build = Module::Build->new - ( module_name => 'Foo::Bar', - license => 'perl', - create_makefile_pl => 'passthrough' ); - ... + # In a Build.PL : + use Module::Build; + my $build = Module::Build->new + ( module_name => 'Foo::Bar', + license => 'perl', + create_makefile_pl => 'passthrough' ); + ... + =head1 DESCRIPTION @@ -295,11 +297,12 @@ Module::Build::Compat also provides some code that helps out the Makefile.PL at runtime. + =head1 METHODS =over 4 -=item create_makefile_pl( $style, $build ) +=item create_makefile_pl($style, $build) Creates a Makefile.PL in the current directory in one of several styles, based on the supplied Module::Build object C<$build>. This is @@ -340,7 +343,7 @@ =back -=item run_build_pl( args => \@ARGV ) +=item run_build_pl(args => \@ARGV) This method runs the Build.PL script, passing it any arguments the user may have supplied to the C<perl Makefile.PL> command. Because @@ -363,7 +366,6 @@ =back - =item write_makefile() This method writes a 'dummy' Makefile that will pass all commands @@ -381,6 +383,7 @@ =back + =head1 SCENARIOS So, some common scenarios are: @@ -393,7 +396,7 @@ script), and give installation directions in a README or INSTALL document explaining how to install the module. In particular, explain that the user must install Module::Build before installing your -module. +module. Note that if you do this, you may make things easier for yourself, but harder for people with older versions of CPAN or CPANPLUS on their @@ -426,9 +429,11 @@ =back + =head1 AUTHOR -Ken Williams, ke...@ma... +Ken Williams <ke...@ma...> + =head1 COPYRIGHT @@ -437,8 +442,10 @@ This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. + =head1 SEE ALSO Module::Build(3), ExtUtils::MakeMaker(3) + =cut Index: Notes.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Notes.pm,v retrieving revision 1.8 retrieving revision 1.9 diff -u -d -r1.8 -r1.9 --- Notes.pm 14 Jul 2005 03:03:56 -0000 1.8 +++ Notes.pm 2 Dec 2005 12:12:21 -0000 1.9 @@ -186,6 +186,7 @@ $notes_name - Configuration for $module_name + =head1 SYNOPSIS use $notes_name; @@ -199,6 +200,7 @@ $notes_name->set_feature(bar => \$new_value); $notes_name->write; # Save changes + =head1 DESCRIPTION This module holds the configuration data for the C<$module_name> @@ -208,6 +210,7 @@ module, and you should attempt to understand the repercussions of your actions. + =head1 METHODS =over 4 @@ -259,6 +262,7 @@ =back + =head1 AUTHOR C<$notes_name> was automatically created using C<Module::Build>. Index: Base.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Base.pm,v retrieving revision 1.533 retrieving revision 1.534 diff -u -d -r1.533 -r1.534 --- Base.pm 1 Dec 2005 08:48:10 -0000 1.533 +++ Base.pm 2 Dec 2005 12:12:21 -0000 1.534 @@ -449,7 +449,7 @@ my $module_name = $self->module_name or die "The config_data feature requires that 'module_name' be set"; - my $notes_name = $module_name . '::ConfigData'; + my $notes_name = $module_name . '::ConfigData'; # TODO: Customize name ??? my $notes_pm = File::Spec->catfile($self->blib, 'lib', split /::/, "$notes_name.pm"); return if $self->up_to_date([$self->config_file('config_data'), $self->config_file('features')], $notes_pm); @@ -3736,7 +3736,7 @@ =head1 AUTHOR -Ken Williams, ke...@ma... +Ken Williams <ke...@ma...> =head1 COPYRIGHT Index: Cookbook.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Cookbook.pm,v retrieving revision 1.17 retrieving revision 1.18 diff -u -d -r1.17 -r1.18 --- Cookbook.pm 27 Nov 2005 02:53:30 -0000 1.17 +++ Cookbook.pm 2 Dec 2005 12:12:21 -0000 1.18 @@ -1,9 +1,11 @@ package Module::Build::Cookbook; + =head1 NAME Module::Build::Cookbook - Examples of Module::Build Usage + =head1 DESCRIPTION C<Module::Build> isn't conceptually very complicated, but examples are @@ -15,17 +17,19 @@ The definitional of how stuff works is in the main C<Module::Build> documentation. It's best to get familiar with that too. + =head1 BASIC RECIPES + =head2 The basic installation recipe for modules that use Module::Build In most cases, you can just issue the following commands from your shell: - perl Build.PL - Build - Build test - Build install + perl Build.PL + Build + Build test + Build install There's nothing complicated here - first you're running a script called F<Build.PL>, then you're running a (newly-generated) script @@ -37,10 +41,10 @@ of perl installed, you can install to one particular perl's library directories like so: - /usr/bin/perl5.8.1 Build.PL - Build - Build test - Build install + /usr/bin/perl5.8.1 Build.PL + Build + Build test + Build install The F<Build> script knows what perl was used to run C<Build.PL>, so you don't need to re-invoke the F<Build> script with the complete perl @@ -50,10 +54,11 @@ If the current directory (usually called '.') isn't in your path, you can do C<./Build> or C<perl Build> to run the script: - /usr/bin/perl Build.PL - ./Build - ./Build test - ./Build install + /usr/bin/perl Build.PL + ./Build + ./Build test + ./Build install + =head2 Making a CPAN.pm-compatible distribution @@ -62,11 +67,11 @@ versions, do the following: Create a file in your distribution named F<Makefile.PL>, with the -following contents: +following contents: - use Module::Build::Compat; - Module::Build::Compat->run_build_pl(args => \@ARGV); - Module::Build::Compat->write_makefile(); + use Module::Build::Compat; + Module::Build::Compat->run_build_pl(args => \@ARGV); + Module::Build::Compat->write_makefile(); Now CPAN will work as usual, i.e.: `perl Makefile.PL`, `make`, `make test`, and `make install`. @@ -74,6 +79,7 @@ Alternatively, see the C<create_makefile_pl> parameter to the C<< Module::Build->new() >> method. + =head2 Installing modules using the programmatic interface If you need to build, test, and/or install modules from within some @@ -83,14 +89,15 @@ subclass) and then invoke its C<dispatch()> method to run various actions. - my $b = Module::Build->new( - module_name => 'Foo::Bar', - license => 'perl', - requires => { 'Some::Module' => '1.23' }, - ); - $b->dispatch('build'); - $b->dispatch('test', verbose => 1); - $b->dispatch('install'); + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', + license => 'perl', + requires => { 'Some::Module' => '1.23' }, + ); + $build->dispatch('build'); + $build->dispatch('test', verbose => 1); + $build->dispatch('install'); The first argument to C<dispatch()> is the name of the action, and any following arguments are named parameters. @@ -98,6 +105,7 @@ This is the interface we use to test Module::Build itself in the regression tests. + =head2 Installing to a temporary directory To create packages for package managers like RedHat's C<rpm> or @@ -105,7 +113,8 @@ first and then create the package from that temporary installation. To do this, specify the C<destdir> parameter to the C<install> action: - Build install destdir=/tmp/my-package-1.003 + ./Build install --destdir /tmp/my-package-1.003 + =head2 Running a single test file @@ -128,16 +137,17 @@ =head1 ADVANCED RECIPES + =head2 Changing the order of the build process The C<build_elements> property specifies the steps C<Module::Build> will take when building a distribution. To change the build order, change the order of the entries in that property: - # Process pod files first - my @e = @{$build->build_elements}; - my $i = grep {$e[$_] eq 'pod'} 0..$#e; - unshift @e, splice @e, $i, 1; + # Process pod files first + my @e = @{$build->build_elements}; + my $i = grep {$e[$_] eq 'pod'} 0..$#e; + unshift @e, splice @e, $i, 1; Currently, C<build_elements> has the following default value: @@ -147,6 +157,7 @@ non-obvious (and non-documented!) ordering dependencies in the C<Module::Build> code. + =head2 Dealing with more than one perl installation If you have more than one C<perl> interpreter installed on your @@ -175,18 +186,18 @@ Sometimes you might have extra types of files that you want to install alongside the standard types like F<.pm> and F<.pod> files. For -instance, you might have a F<Foo.dat> file containing some data -related to the C<Boo::Baz> module. Assuming the data doesn't need to +instance, you might have a F<Bar.dat> file containing some data +related to the C<Foo::Bar> module. Assuming the data doesn't need to be created on the fly, the best place for it to end up is probably as -F<Boo/Baz/Foo.dat> somewhere in perl's C<@INC> path so C<Boo::Baz> can +F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can access it easily at runtime. The following code from a sample C<Build.PL> file demonstrates how to accomplish this: use Module::Build; - my $build = new Module::Build + my $build = Module::Build->new ( - module_name => 'Boo::Baz', - ... + module_name => 'Foo::Bar', + ...other stuff here... ); $build->add_build_element('dat'); $build->create_build_script; @@ -202,9 +213,9 @@ use Module::Build; my $build = new Module::Build ( - module_name => 'Boo::Baz', - dat_files => {'some/dir/Foo.dat' => 'lib/Boo/Baz/Foo.dat'}, - ... + module_name => 'Foo::Bar', + dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'}, + ...other stuff here... ); $build->add_build_element('dat'); $build->create_build_script; @@ -224,8 +235,8 @@ EOF my $build = $class->new ( - module_name => 'Boo::Baz', - ... + module_name => 'Foo::Bar', + ...other stuff here... ); $build->add_build_element('dat'); $build->create_build_script; @@ -238,6 +249,7 @@ that first appeared in version 0.26. Before that it could certainly still be done, but the simple cases took a bit more work. + =head2 Adding new elements to the install process By default, Module::Build creates seven subdirectories of the F<blib/> @@ -252,14 +264,15 @@ should be installed. To do this, use the C<install_path> parameter to the C<new()> method: - my $b = Module::Build->new - (... - install_path => { conf => $installation_path } - ); + my $build = Module::Build->new + ( + ...other stuff here... + install_path => { conf => $installation_path } + ); Or you can call the C<install_path()> method later: - $b->install_path->{conf} || $installation_path; + $build->install_path->{conf} || $installation_path; (Sneakily, or perhaps uglily, C<install_path()> returns a reference to a hash of install paths, and you can modify that hash to your heart's @@ -276,11 +289,13 @@ See also L<"Adding new file types to the build process"> for how to create the stuff in F<blib/conf/> in the first place. + =head1 EXAMPLES ON CPAN Several distributions on CPAN are making good use of various features of Module::Build. They can serve as real-world examples for others. + =head2 SVN-Notify-Mirror L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/> @@ -311,7 +326,8 @@ =head1 AUTHOR -Ken Williams, ke...@ma... +Ken Williams <ke...@ma...> + =head1 COPYRIGHT @@ -320,6 +336,7 @@ This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. + =head1 SEE ALSO perl(1), Module::Build(3) Index: ModuleInfo.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/ModuleInfo.pm,v retrieving revision 1.14 retrieving revision 1.15 diff -u -d -r1.14 -r1.15 --- ModuleInfo.pm 14 Oct 2005 00:45:52 -0000 1.14 +++ ModuleInfo.pm 2 Dec 2005 12:12:21 -0000 1.15 @@ -346,16 +346,19 @@ ModuleInfo - Gather package and POD information from a perl module files + =head1 DESCRIPTION -=head2 new_from_file( $filename [ , collect_pod => 1 ] ) +=over 4 + +=item new_from_file($filename, collect_pod => 1) Construct a ModuleInfo object given the path to a file. Takes an optional arguement C<collect_pod> which is a boolean that determines whether POD data is collected and stored for reference. POD data is not collected by default. POD headings are always collected. -=head2 new_from_module( $module [ , collect_pod => 1, inc => \@dirs ] ) +=item new_from_module($module, collect_pod => 1, inc => \@dirs) Construct a ModuleInfo object given a module or package name. In addition to accepting the C<collect_pod> argument as described above, this @@ -363,41 +366,41 @@ of directories to search for the module. If none are given, the default is @INC. -=head2 name( ) +=item name() Returns the name of the package represented by this module. If there are more than one packages, it makes a best guess based on the filename. If it's a script (i.e. not a *.pm) the package name is 'main'. -=head2 version( [ $package ] ) +=item version($package) Returns the version as defined by the $VERSION variable for the package as returned by the C<name> method if no arguments are given. If given the name of a package it will attempt to return the version of that package if it is specified in the file. -=head2 filename( ) +=item filename() Returns the absolute path to the file. -=head2 packages_inside( ) +=item packages_inside() Returns a list of packages. -=head2 pod_inside( ) +=item pod_inside() Returns a list of POD sections. -=head2 contains_pod( ) +=item contains_pod() Returns true if there is any POD in the file. -=head2 pod( $section ) +=item pod($section) Returns the POD data in the given section. -=head2 find_module_by_name( $module [ , \@dirs ] ) +=item find_module_by_name($module, \@dirs) Returns the path to a module given the module or package name. A list of directories can be passed in as an optional paramater, otherwise @@ -405,7 +408,7 @@ Can be called as either an object or a class method. -=head2 find_module_dir_by_name( $module [ , \@dirs ] ) +=item find_module_dir_by_name($module, \@dirs) Returns the entry in C<@dirs> (or C<@INC> by default) that contains the module C<$module>. A list of directories can be passed in as an @@ -413,4 +416,25 @@ Can be called as either an object or a class method. +=back + + +=head1 AUTHOR + +Ken Williams <ke...@ma...>, Randy W. Sims <Ra...@Th...> + + +=head1 COPYRIGHT + +Copyright (c) 2001-2005 Ken Williams. All rights reserved. + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + + +=head1 SEE ALSO + +perl(1), Module::Build(3) + =cut + Index: PodParser.pm =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/PodParser.pm,v retrieving revision 1.7 retrieving revision 1.8 diff -u -d -r1.7 -r1.8 --- PodParser.pm 9 Sep 2005 18:35:27 -0000 1.7 +++ PodParser.pm 2 Dec 2005 12:12:21 -0000 1.8 @@ -85,7 +85,6 @@ } } - sub textblock { my ($self, $text) = @_; $text =~ s/^\s+//; Index: Authoring.pod =================================================================== RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Authoring.pod,v retrieving revision 1.26 retrieving revision 1.27 diff -u -d -r1.26 -r1.27 --- Authoring.pod 30 Nov 2005 10:46:04 -0000 1.26 +++ Authoring.pod 2 Dec 2005 12:12:21 -0000 1.27 @@ -12,11 +12,11 @@ my $build = Module::Build->new ( module_name => 'Foo::Bar', - license => 'perl', + license => 'perl', requires => { - 'perl' => '5.6.1', - 'Some::Module' => '1.23', - 'Other::Module' => '>= 1.2, != 1.5, < 2.0', + 'perl' => '5.6.1', + 'Some::Module' => '1.23', + 'Other::Module' => '>= 1.2, != 1.5, < 2.0', }, ); $build->create_build_script; @@ -26,8 +26,8 @@ use Module::Build; Module::Build->new( - module_name => 'Foo::Bar', - license => 'perl', + module_name => 'Foo::Bar', + license => 'perl', )->create_build_script; The model used by C<Module::Build> is a lot like the C<MakeMaker> @@ -75,15 +75,15 @@ the user a question during C<perl Build.PL>, then use their answer during a regression test: - # In Build.PL: - my $color = $build->prompt("What is your favorite color?"); - $build->notes(color => $color); + # In Build.PL: + my $color = $build->prompt("What is your favorite color?"); + $build->notes(color => $color); - # In t/colortest.t: - use Module::Build; - my $build = Module::Build->current; - my $color = $build->notes('color'); - ... + # In t/colortest.t: + use Module::Build; + my $build = Module::Build->current; + my $color = $build->notes('color'); + ... The way the C<current()> method is currently implemented, there may be slight differences between the C<$build> object in Build.PL and the @@ -119,24 +119,22 @@ instance, for a module that could optionally use either MySQL or PostgreSQL databases, you might use C<auto_features> like this: - my $b = Module::Build->new + my $build = Module::Build->new ( - ... other stuff here... - auto_features => - { - pg_support => - { - description => "Interface with Postgres databases", - requires => { 'DBD::Pg' => 23.3, - 'DateTime::Format::Pg' => 0 }, - }, - mysql_support => - { - description => "Interface with MySQL databases", - requires => { 'DBD::mysql' => 17.9, - 'DateTime::Format::MySQL' => 0}, - }, - ); + ...other stuff here... + auto_features => { + pg_support => { + description => "Interface with Postgres databases", + requires => { 'DBD::Pg' => 23.3, + 'DateTime::Format::Pg' => 0 }, + }, + mysql_support => { + description => "Interface with MySQL databases", + requires => { 'DBD::mysql' => 17.9, + 'DateTime::Format::MySQL' => 0 }, + }, + } + ); For each feature named, the required prerequisites will be checked, and if there are no failures, the feature will be enabled (set to C<1>). @@ -295,19 +293,21 @@ and linker phases when compiling/linking C code. For example, to tell the compiler that your code is C++, you might do: - my build = Module::Build->new( - module_name => 'Spangly', + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', extra_compiler_flags => ['-x', 'c++'], - ); + ); To link your XS code against glib you might write something like: - my build = Module::Build->new( - module_name => 'Spangly', + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', dynamic_config => 1, extra_compiler_flags => scalar `glib-config --cflags`, extra_linker_flags => scalar `glib-config --libs`, - ); + ); =item get_options @@ -354,24 +354,25 @@ unreferenced specifications, for which the result will also be stored in the hash returned by C<args()>. For example: - my $loud = 0; - my $build = Module::Build->new( - module_name => 'Spangly', + my $loud = 0; + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', get_options => { - loud => { store => \$loud }, - dbd => { type => '=s' }, - quantity => { type => '+' }, + loud => { store => \$loud }, + dbd => { type => '=s' }, + quantity => { type => '+' }, } - ); + ); - print STDERR "HEY, ARE YOU LISTENING??\n" if $loud; - print "We'll use the ", $build->args('dbd'), " DBI driver\n"; - print "Are you sure you want that many?\n" - if $build->args('quantity') > 2; + print STDERR "HEY, ARE YOU LISTENING??\n" if $loud; + print "We'll use the ", $build->args('dbd'), " DBI driver\n"; + print "Are you sure you want that many?\n" + if $build->args('quantity') > 2; The arguments for such a specification can be called like so: - % perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity + perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity B<WARNING:> Any option specifications that conflict with Module::Build's own options (defined by its properties) will throw an exception. @@ -384,6 +385,20 @@ files. May be given as a string indicating a single directory, or as a list reference indicating multiple directories. +=item install_path + +You can set paths for individual installable elements by using the +C<install_path> parameter: + + my $build = Module::Build->new + ( + ...other stuff here... + install_path => { + lib => '/foo/lib', + arch => '/foo/lib/arch', + } + ); + =item installdirs Determines where files are installed within the normal perl hierarchy @@ -522,17 +537,27 @@ The files are specified with the C<.PL> files as hash keys, and the file(s) they generate as hash values, like so: - my $build = Module::Build->new - ( module_name => 'Foo::Bar', + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', ... - PL_files => { 'lib/Bar.pm.PL' => 'lib/Bar.pm', - 'lib/Foo.PL' => [ 'lib/Foo1.pm', 'lib/Foo2.pm' ], - }, - ); + PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' }, + ); Note that the path specifications are I<always> given in Unix-like format, not in the style of the local system. +If your C<.PL> scripts don't create any files, or if they create files +with unexpected names, or even if they create multiple files, you can +indicate that so that Module::Build can properly handle these created +files: + + PL_files => { + 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm', + 'lib/something.PL' => ['/lib/something', '/lib/else'], + 'lib/funny.PL' => [], + } + =item pm_files An optional parameter specifying the set of C<.pm> files in this @@ -547,11 +572,12 @@ distribution, you could specify your layout in your C<Build.PL> like this: - my $build = Module::Build->new - ( module_name => 'Foo::Bar', + my $build = Module::Build->new + ( + module_name => 'Foo::Bar', ... pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' }, - ); + ); Note that the values should include C<lib/>, because this is where they would be found in a "normal" Module::Build-style distribution. @@ -766,12 +792,12 @@ The returned hash reference has the following structure: - { - ok => $whether_the_dependency_is_satisfied, - have => $version_already_installed, - need => $version_requested, # Same as incoming $version argument - message => $informative_error_message, - } + { + ok => $whether_the_dependency_is_satisfied, + have => $version_already_installed, + need => $version_requested, # Same as incoming $version argument + message => $informative_error_message, + } If no version of C<$module> is currently installed, the C<have> value will be the string C<< "<none>" >>. Otherwise the C<have> value will @@ -795,12 +821,12 @@ C<$module> installed on the system. This allows you to do the following: - my $installed = $m->check_installed_version('DBI', '1.15'); - if ($installed) { - print "Congratulations, version $installed of DBI is installed.\n"; - } else { - die "Sorry, you must install DBI.\n"; - } + my $installed = $build->check_installed_version('DBI', '1.15'); + if ($installed) { + print "Congratulations, version $installed of DBI is installed.\n"; + } else { + die "Sorry, you must install DBI.\n"; + } If the check fails, we return false and set C<$@> to an informative error message. @@ -941,7 +967,7 @@ Custom options that have not been registered must be passed in as a hash reference in a key named "args": - $mb->dispatch('foo', verbose => 1, args => { my_option => 'value' }); + $build->dispatch('foo', verbose => 1, args => { my_option => 'value' }); This method is intended to be used to programmatically invoke build actions, e.g. by applications controlling Module::Build-based builds @@ -1131,19 +1157,19 @@ conflicting) modules. The associated values of those are hash references indicating some information about the failure. For example: - { - have => '0.42', - need => '0.59', - message => 'Version 0.42 is installed, but we need version 0.59', - } + { + have => '0.42', + need => '0.59', + message => 'Version 0.42 is installed, but we need version 0.59', + } or - { - have => '<none>', - need => '0.59', - message => 'Prerequisite Foo isn't installed', - } + { + have => '<none>', + need => '0.59', + message => 'Prerequisite Foo isn't installed', + } This hash has the same structure as the hash returned by the C<check_installed_status()> method, except that in the case of @@ -1153,13 +1179,13 @@ Examples: # Check a required dependency on Foo::Bar - if ( $m->prereq_failures->{requires}{Foo::Bar} ) { ... + if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ... # Check whether there were any failures - if ( $m->prereq_failures ) { ... + if ( $build->prereq_failures ) { ... # Show messages for all failures - my $failures = $m->prereq_failures; + my $failures = $build->prereq_failures; while (my ($type, $list) = each %$failures) { while (my ($name, $hash) = each %$list) { print "Failure for $name: $hash->{message}\n"; @@ -1278,10 +1304,12 @@ The prerequisites are given in a hash reference, where the keys are the module names and the values are version specifiers: - requires => {Foo::Module => '2.4', - Bar::Module => 0, - Ken::Module => '>= 1.2, != 1.5, < 2.0', - perl => '5.6.0'}, + requires => { + Foo::Module => '2.4', + Bar::Module => 0, + Ken::Module => '>= 1.2, != 1.5, < 2.0', + perl => '5.6.0' + }, These four version specifiers have different effects. The value C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be @@ -1321,20 +1349,20 @@ a module non-interactively. For instance, the following Perl script will invoke the entire build/install procedure: - my $m = Module::Build->new(module_name => 'MyModule'); - $m->dispatch('build'); - $m->dispatch('test'); - $m->dispatch('install'); + my $build = Module::Build->new(module_name => 'MyModule'); + $build->dispatch('build'); + $build->dispatch('test'); + $build->dispatch('install'); If any of these steps encounters an error, it will throw a fatal exception. You can also pass arguments as part of the build process: - my $m = Module::Build->new(module_name => 'MyModule'); - $m->dispatch('build'); - $m->dispatch('test', verbose => 1); - $m->dispatch('install', sitelib => '/my/secret/place/'); + my $build = Module::Build->new(module_name => 'MyModule'); + $build->dispatch('build'); + $build->dispatch('test', verbose => 1); + $build->dispatch('install', sitelib => '/my/secret/place/'); Building and installing modules in this way skips creating the C<Build> script. @@ -1374,16 +1402,18 @@ ------ in Build.PL: ---------- #!/usr/bin/perl - - use lib qw(/nonstandard/library/path); + + use lib q(/nonstandard/library/path); use My::Builder; # Or whatever you want to call it - - my $m = My::Builder->new - (module_name=> 'Next::Big::Thing', # All the regular args... - license=> 'perl', - dist_author=> 'A N Other <me...@he...>', - requires=> {Carp => 0}); - $m->create_build_script; + + my $build = My::Builder->new + ( + module_name => 'Foo::Bar', # All the regular args... + license => 'perl', + dist_author => 'A N Other <me...@he...>', + requires => { Carp => 0 } + ); + $build->create_build_script; This is relatively straightforward, and is the best way to do things if your My::Builder class contains lots of code. The @@ -1398,24 +1428,26 @@ ------ in Build.PL: ---------- #!/usr/bin/perl - + use Module::Build; my $class = Module::Build->subclass ( class => 'My::Builder', code => q{ - sub ACTION_foo { - print "I'm fooing to death!\n"; - } + sub ACTION_foo { + print "I'm fooing to death!\n"; + } }, ); - - my $m = $class->new - (module_name=> 'Next::Big::Thing', # All the regular args... - license=> 'perl', - dist_author=> 'A N Other <me...@he...>', - requires=> {Carp => 0}); - $m->create_build_script; + + my $build = $class->new + ( + module_name => 'Foo::Bar', # All the regular args... + license => 'perl', + dist_author => 'A N Other <me...@he...>', + requires => { Carp => 0 } + ); + $build->create_build_script; Behind the scenes, this actually does create a C<.pm> file, since the code you provide must persist after Build.PL is run if it is to be @@ -1446,7 +1478,7 @@ following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker doesn't try to run your F<Build.PL> as a normal F<.PL> file: - PL_FILES => {}, + PL_FILES => {}, You may also be interested in looking at the C<Module::Build::Compat> module, which can automatically create various kinds of F<Makefile.PL> |
