"Fossies" - the Fresh Open Source Software Archive

Member "Module-Build-0.4224/lib/Module/Build/Cookbook.pm" (30 May 2017, 17337 Bytes) of package /linux/privat/Module-Build-0.4224.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Cookbook.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 0.4222_vs_0.4224.

    1 package Module::Build::Cookbook;
    2 use strict;
    3 use warnings;
    4 our $VERSION = '0.4224';
    5 
    6 
    7 =head1 NAME
    8 
    9 Module::Build::Cookbook - Examples of Module::Build Usage
   10 
   11 =head1 DESCRIPTION
   12 
   13 C<Module::Build> isn't conceptually very complicated, but examples are
   14 always helpful.  The following recipes should help developers and/or
   15 installers put together the pieces from the other parts of the
   16 documentation.
   17 
   18 
   19 =head1 BASIC RECIPES
   20 
   21 
   22 =head2 Installing modules that use Module::Build
   23 
   24 In most cases, you can just issue the following commands:
   25 
   26   perl Build.PL
   27   ./Build
   28   ./Build test
   29   ./Build install
   30 
   31 There's nothing complicated here - first you're running a script
   32 called F<Build.PL>, then you're running a (newly-generated) script
   33 called F<Build> and passing it various arguments.
   34 
   35 The exact commands may vary a bit depending on how you invoke perl
   36 scripts on your system.  For instance, if you have multiple versions
   37 of perl installed, you can install to one particular perl's library
   38 directories like so:
   39 
   40   /usr/bin/perl5.8.1 Build.PL
   41   ./Build
   42   ./Build test
   43   ./Build install
   44 
   45 If you're on Windows where the current directory is always searched
   46 first for scripts, you'll probably do something like this:
   47 
   48   perl Build.PL
   49   Build
   50   Build test
   51   Build install
   52 
   53 On the old Mac OS (version 9 or lower) using MacPerl, you can
   54 double-click on the F<Build.PL> script to create the F<Build> script,
   55 then double-click on the F<Build> script to run its C<build>, C<test>,
   56 and C<install> actions.
   57 
   58 The F<Build> script knows what perl was used to run F<Build.PL>, so
   59 you don't need to re-invoke the F<Build> script with the complete perl
   60 path each time.  If you invoke it with the I<wrong> perl path, you'll
   61 get a warning or a fatal error.
   62 
   63 =head2 Modifying Config.pm values
   64 
   65 C<Module::Build> relies heavily on various values from perl's
   66 C<Config.pm> to do its work.  For example, default installation paths
   67 are given by C<installsitelib> and C<installvendorman3dir> and
   68 friends, C linker & compiler settings are given by C<ld>,
   69 C<lddlflags>, C<cc>, C<ccflags>, and so on.  I<If you're pretty sure
   70 you know what you're doing>, you can tell C<Module::Build> to pretend
   71 there are different values in F<Config.pm> than what's really there,
   72 by passing arguments for the C<--config> parameter on the command
   73 line:
   74 
   75   perl Build.PL --config cc=gcc --config ld=gcc
   76 
   77 Inside the C<Build.PL> script the same thing can be accomplished by
   78 passing values for the C<config> parameter to C<new()>:
   79 
   80  my $build = Module::Build->new
   81    (
   82     ...
   83     config => { cc => 'gcc', ld => 'gcc' },
   84     ...
   85    );
   86 
   87 In custom build code, the same thing can be accomplished by calling
   88 the L<Module::Build/config> method:
   89 
   90  $build->config( cc => 'gcc' );     # Set
   91  $build->config( ld => 'gcc' );     # Set
   92  ...
   93  my $linker = $build->config('ld'); # Get
   94 
   95 
   96 =head2 Installing modules using the programmatic interface
   97 
   98 If you need to build, test, and/or install modules from within some
   99 other perl code (as opposed to having the user type installation
  100 commands at the shell), you can use the programmatic interface.
  101 Create a Module::Build object (or an object of a custom Module::Build
  102 subclass) and then invoke its C<dispatch()> method to run various
  103 actions.
  104 
  105   my $build = Module::Build->new
  106     (
  107      module_name => 'Foo::Bar',
  108      license     => 'perl',
  109      requires    => { 'Some::Module'   => '1.23' },
  110     );
  111   $build->dispatch('build');
  112   $build->dispatch('test', verbose => 1);
  113   $build->dispatch('install');
  114 
  115 The first argument to C<dispatch()> is the name of the action, and any
  116 following arguments are named parameters.
  117 
  118 This is the interface we use to test Module::Build itself in the
  119 regression tests.
  120 
  121 
  122 =head2 Installing to a temporary directory
  123 
  124 To create packages for package managers like RedHat's C<rpm> or
  125 Debian's C<deb>, you may need to install to a temporary directory
  126 first and then create the package from that temporary installation.
  127 To do this, specify the C<destdir> parameter to the C<install> action:
  128 
  129   ./Build install --destdir /tmp/my-package-1.003
  130 
  131 This essentially just prepends all the installation paths with the
  132 F</tmp/my-package-1.003> directory.
  133 
  134 
  135 =head2 Installing to a non-standard directory
  136 
  137 To install to a non-standard directory (for example, if you don't have
  138 permission to install in the system-wide directories), you can use the
  139 C<install_base> or C<prefix> parameters:
  140 
  141   ./Build install --install_base /foo/bar
  142 
  143 See L<Module::Build/"INSTALL PATHS"> for a much more complete
  144 discussion of how installation paths are determined.
  145 
  146 
  147 =head2 Installing in the same location as ExtUtils::MakeMaker
  148 
  149 With the introduction of C<--prefix> in Module::Build 0.28 and
  150 C<INSTALL_BASE> in C<ExtUtils::MakeMaker> 6.31 its easy to get them both
  151 to install to the same locations.
  152 
  153 First, ensure you have at least version 0.28 of Module::Build
  154 installed and 6.31 of C<ExtUtils::MakeMaker>.  Prior versions have
  155 differing (and in some cases quite strange) installation behaviors.
  156 
  157 The following installation flags are equivalent between
  158 C<ExtUtils::MakeMaker> and C<Module::Build>.
  159 
  160     MakeMaker             Module::Build
  161     PREFIX=...            --prefix ...
  162     INSTALL_BASE=...      --install_base ...
  163     DESTDIR=...           --destdir ...
  164     LIB=...               --install_path lib=...
  165     INSTALLDIRS=...       --installdirs ...
  166     INSTALLDIRS=perl      --installdirs core
  167     UNINST=...            --uninst ...
  168     INC=...               --extra_compiler_flags ...
  169     POLLUTE=1             --extra_compiler_flags -DPERL_POLLUTE
  170 
  171 For example, if you are currently installing C<MakeMaker> modules with
  172 this command:
  173 
  174     perl Makefile.PL PREFIX=~
  175     make test
  176     make install UNINST=1
  177 
  178 You can install into the same location with Module::Build using this:
  179 
  180     perl Build.PL --prefix ~
  181     ./Build test
  182     ./Build install --uninst 1
  183 
  184 =head3 C<prefix> vs C<install_base>
  185 
  186 The behavior of C<prefix> is complicated and depends on
  187 how your Perl is configured.  The resulting installation locations
  188 will vary from machine to machine and even different installations of
  189 Perl on the same machine.  Because of this, it's difficult to document
  190 where C<prefix> will place your modules.
  191 
  192 In contrast, C<install_base> has predictable, easy to explain
  193 installation locations.  Now that C<Module::Build> and C<MakeMaker> both
  194 have C<install_base> there is little reason to use C<prefix> other
  195 than to preserve your existing installation locations.  If you are
  196 starting a fresh Perl installation we encourage you to use
  197 C<install_base>.  If you have an existing installation installed via
  198 C<prefix>, consider moving it to an installation structure matching
  199 C<install_base> and using that instead.
  200 
  201 
  202 =head2 Running a single test file
  203 
  204 C<Module::Build> supports running a single test, which enables you to
  205 track down errors more quickly.  Use the following format:
  206 
  207   ./Build test --test_files t/mytest.t
  208 
  209 In addition, you may want to run the test in verbose mode to get more
  210 informative output:
  211 
  212   ./Build test --test_files t/mytest.t --verbose 1
  213 
  214 I run this so frequently that I define the following shell alias:
  215 
  216   alias t './Build test --verbose 1 --test_files'
  217 
  218 So then I can just execute C<t t/mytest.t> to run a single test.
  219 
  220 
  221 =head1 ADVANCED RECIPES
  222 
  223 
  224 =head2 Making a CPAN.pm-compatible distribution
  225 
  226 New versions of CPAN.pm understand how to use a F<Build.PL> script,
  227 but old versions don't.  If authors want to help users who have old
  228 versions, some form of F<Makefile.PL> should be supplied.  The easiest
  229 way to accomplish this is to use the C<create_makefile_pl> parameter to
  230 C<< Module::Build->new() >> in the C<Build.PL> script, which can
  231 create various flavors of F<Makefile.PL> during the C<dist> action.
  232 
  233 As a best practice, we recommend using the "traditional" style of
  234 F<Makefile.PL> unless your distribution has needs that can't be
  235 accomplished that way.
  236 
  237 The C<Module::Build::Compat> module, which is part of
  238 C<Module::Build>'s distribution, is responsible for creating these
  239 F<Makefile.PL>s.  Please see L<Module::Build::Compat> for the details.
  240 
  241 
  242 =head2 Changing the order of the build process
  243 
  244 The C<build_elements> property specifies the steps C<Module::Build>
  245 will take when building a distribution.  To change the build order,
  246 change the order of the entries in that property:
  247 
  248   # Process pod files first
  249   my @e = @{$build->build_elements};
  250   my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
  251   unshift @e, splice @e, $i, 1;
  252 
  253 Currently, C<build_elements> has the following default value:
  254 
  255   [qw( PL support pm xs pod script )]
  256 
  257 Do take care when altering this property, since there may be
  258 non-obvious (and non-documented!) ordering dependencies in the
  259 C<Module::Build> code.
  260 
  261 
  262 =head2 Adding new file types to the build process
  263 
  264 Sometimes you might have extra types of files that you want to install
  265 alongside the standard types like F<.pm> and F<.pod> files.  For
  266 instance, you might have a F<Bar.dat> file containing some data
  267 related to the C<Foo::Bar> module and you'd like for it to end up as
  268 F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
  269 access it easily at runtime.  The following code from a sample
  270 C<Build.PL> file demonstrates how to accomplish this:
  271 
  272   use Module::Build;
  273   my $build = Module::Build->new
  274     (
  275      module_name => 'Foo::Bar',
  276      ...other stuff here...
  277     );
  278   $build->add_build_element('dat');
  279   $build->create_build_script;
  280 
  281 This will find all F<.dat> files in the F<lib/> directory, copy them
  282 to the F<blib/lib/> directory during the C<build> action, and install
  283 them during the C<install> action.
  284 
  285 If your extra files aren't located in the C<lib/> directory in your
  286 distribution, you can explicitly say where they are, just as you'd do
  287 with F<.pm> or F<.pod> files:
  288 
  289   use Module::Build;
  290   my $build = new Module::Build
  291     (
  292      module_name => 'Foo::Bar',
  293      dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
  294      ...other stuff here...
  295     );
  296   $build->add_build_element('dat');
  297   $build->create_build_script;
  298 
  299 If your extra files actually need to be created on the user's machine,
  300 or if they need some other kind of special processing, you'll probably
  301 want to subclass C<Module::Build> and create a special method to
  302 process them, named C<process_${kind}_files()>:
  303 
  304   use Module::Build;
  305   my $class = Module::Build->subclass(code => <<'EOF');
  306     sub process_dat_files {
  307       my $self = shift;
  308       ... locate and process *.dat files,
  309       ... and create something in blib/lib/
  310     }
  311   EOF
  312   my $build = $class->new
  313     (
  314      module_name => 'Foo::Bar',
  315      ...other stuff here...
  316     );
  317   $build->add_build_element('dat');
  318   $build->create_build_script;
  319 
  320 If your extra files don't go in F<lib/> but in some other place, see
  321 L<"Adding new elements to the install process"> for how to actually
  322 get them installed.
  323 
  324 Please note that these examples use some capabilities of Module::Build
  325 that first appeared in version 0.26.  Before that it could
  326 still be done, but the simple cases took a bit more work.
  327 
  328 
  329 =head2 Adding new elements to the install process
  330 
  331 By default, Module::Build creates seven subdirectories of the F<blib>
  332 directory during the build process: F<lib>, F<arch>, F<bin>,
  333 F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
  334 missing or empty if there's nothing to go in them).  Anything copied
  335 to these directories during the build will eventually be installed
  336 during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
  337 
  338 If you need to create a new custom type of installable element, e.g. C<conf>,
  339 then you need to tell Module::Build where things in F<blib/conf/>
  340 should be installed.  To do this, use the C<install_path> parameter to
  341 the C<new()> method:
  342 
  343   my $build = Module::Build->new
  344     (
  345      ...other stuff here...
  346      install_path => { conf => $installation_path }
  347     );
  348 
  349 Or you can call the C<install_path()> method later:
  350 
  351   $build->install_path(conf => $installation_path);
  352 
  353 The user may also specify the path on the command line:
  354 
  355   perl Build.PL --install_path conf=/foo/path/etc
  356 
  357 The important part, though, is that I<somehow> the install path needs
  358 to be set, or else nothing in the F<blib/conf/> directory will get
  359 installed, and a runtime error during the C<install> action will
  360 result.
  361 
  362 See also L<"Adding new file types to the build process"> for how to
  363 create the stuff in F<blib/conf/> in the first place.
  364 
  365 
  366 =head1 EXAMPLES ON CPAN
  367 
  368 Several distributions on CPAN are making good use of various features
  369 of Module::Build.  They can serve as real-world examples for others.
  370 
  371 
  372 =head2 SVN-Notify-Mirror
  373 
  374 L<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>
  375 
  376 John Peacock, author of the C<SVN-Notify-Mirror> distribution, says:
  377 
  378 =over 4
  379 
  380 =item 1. Using C<auto_features>, I check to see whether two optional
  381 modules are available - SVN::Notify::Config and Net::SSH;
  382 
  383 =item 2. If the S::N::Config module is loaded, I automatically
  384 generate test files for it during Build (using the C<PL_files>
  385 property).
  386 
  387 =item 3. If the C<ssh_feature> is available, I ask if the user wishes
  388 to perform the ssh tests (since it requires a little preliminary
  389 setup);
  390 
  391 =item 4. Only if the user has C<ssh_feature> and answers yes to the
  392 testing, do I generate a test file.
  393 
  394 I'm sure I could not have handled this complexity with EU::MM, but it
  395 was very easy to do with M::B.
  396 
  397 =back
  398 
  399 
  400 =head2 Modifying an action
  401 
  402 Sometimes you might need an to have an action, say C<./Build install>,
  403 do something unusual.  For instance, you might need to change the
  404 ownership of a file or do something else peculiar to your application.
  405 
  406 You can subclass C<Module::Build> on the fly using the C<subclass()>
  407 method and override the methods that perform the actions.  You may
  408 need to read through C<Module::Build::Authoring> and
  409 C<Module::Build::API> to find the methods you want to override.  All
  410 "action" methods are implemented by a method called "ACTION_" followed
  411 by the action's name, so here's an example of how it would work for
  412 the C<install> action:
  413 
  414   # Build.PL
  415   use Module::Build;
  416   my $class = Module::Build->subclass(
  417       class => "Module::Build::Custom",
  418       code => <<'SUBCLASS' );
  419 
  420   sub ACTION_install {
  421       my $self = shift;
  422       # YOUR CODE HERE
  423       $self->SUPER::ACTION_install;
  424   }
  425   SUBCLASS
  426 
  427   $class->new(
  428       module_name => 'Your::Module',
  429       # rest of the usual Module::Build parameters
  430   )->create_build_script;
  431 
  432 
  433 =head2 Adding an action
  434 
  435 You can add a new C<./Build> action simply by writing the method for
  436 it in your subclass.  Use C<depends_on> to declare that another action
  437 must have been run before your action.
  438 
  439 For example, let's say you wanted to be able to write C<./Build
  440 commit> to test your code and commit it to Subversion.
  441 
  442   # Build.PL
  443   use Module::Build;
  444   my $class = Module::Build->subclass(
  445       class => "Module::Build::Custom",
  446       code => <<'SUBCLASS' );
  447 
  448   sub ACTION_commit {
  449       my $self = shift;
  450 
  451       $self->depends_on("test");
  452       $self->do_system(qw(svn commit));
  453   }
  454   SUBCLASS
  455 
  456 
  457 =head2 Bundling Module::Build
  458 
  459 Note: This section probably needs an update as the technology improves
  460 (see contrib/bundle.pl in the distribution).
  461 
  462 Suppose you want to use some new-ish features of Module::Build,
  463 e.g. newer than the version of Module::Build your users are likely to
  464 already have installed on their systems.  The first thing you should
  465 do is set C<configure_requires> to your minimum version of
  466 Module::Build.  See L<Module::Build::Authoring>.
  467 
  468 But not every build system honors C<configure_requires> yet.  Here's
  469 how you can ship a copy of Module::Build, but still use a newer
  470 installed version to take advantage of any bug fixes and upgrades.
  471 
  472 First, install Module::Build into F<Your-Project/inc/Module-Build>.
  473 CPAN will not index anything in the F<inc> directory so this copy will
  474 not show up in CPAN searches.
  475 
  476     cd Module-Build
  477     perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
  478     ./Build test
  479     ./Build install
  480 
  481 You should now have all the Module::Build .pm files in
  482 F<Your-Project/inc/Module-Build/lib/perl5>.
  483 
  484 Next, add this to the top of your F<Build.PL>.
  485 
  486     my $Bundled_MB = 0.30;  # or whatever version it was.
  487 
  488     # Find out what version of Module::Build is installed or fail quietly.
  489     # This should be cross-platform.
  490     my $Installed_MB =
  491         `$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1"`;
  492 
  493     # some operating systems put a newline at the end of every print.
  494     chomp $Installed_MB;
  495 
  496     $Installed_MB = 0 if $?;
  497 
  498     # Use our bundled copy of Module::Build if it's newer than the installed.
  499     unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
  500 
  501     require Module::Build;
  502 
  503 And write the rest of your F<Build.PL> normally.  Module::Build will
  504 remember your change to C<@INC> and use it when you run F<./Build>.
  505 
  506 In the future, we hope to provide a more automated solution for this
  507 scenario; see C<inc/latest.pm> in the Module::Build distribution for
  508 one indication of the direction we're moving.
  509 
  510 
  511 =head1 AUTHOR
  512 
  513 Ken Williams <kwilliams@cpan.org>
  514 
  515 
  516 =head1 COPYRIGHT
  517 
  518 Copyright (c) 2001-2008 Ken Williams.  All rights reserved.
  519 
  520 This library is free software; you can redistribute it and/or
  521 modify it under the same terms as Perl itself.
  522 
  523 
  524 =head1 SEE ALSO
  525 
  526 perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
  527 L<Module::Build::API>(3)
  528 
  529 =cut