cvs commit: httpd-test/perl-framework/Apache-Test/lib/Apache TestMM.pm

[st...@apache.org]

stas        2003/07/18 01:24:04

  Modified:    perl-framework/Apache-Test/lib/Apache TestMM.pm
  Log:
  add basic docs
  
  Revision  Changes    Path
  1.28      +89 -0     httpd-test/perl-framework/Apache-Test/lib/Apache/TestMM.pm
  
  Index: TestMM.pm
  ===================================================================
  RCS file: /home/cvs/httpd-test/perl-framework/Apache-Test/lib/Apache/TestMM.pm,v
  retrieving revision 1.27
  retrieving revision 1.28
  diff -u -r1.27 -r1.28
  --- TestMM.pm	14 May 2003 22:57:40 -0000	1.27
  +++ TestMM.pm	18 Jul 2003 08:24:04 -0000	1.28
  @@ -100,3 +100,92 @@
   }
   
   1;
  +
  +=head1 NAME
  +
  +Apache::TestMM - Provide MakeMaker Wrapper Methods
  +
  +=head1 SYNOPSIS
  +
  +  require Apache::TestMM;
  +  
  +  # import MY::test and MY::clean overrides for MM
  +  Apache::TestMM->import(qw(test clean));
  +  
  +  # parse command line args
  +  Apache::TestMM::filter_args();
  +  
  +  # autogenerate the script
  +  Apache::TestMM::generate_script('t/TEST');
  +
  +=head1 DESCRIPTION
  +
  +C<Apache::TestMM> provides wrappers for the C<ExtUtils::MakeMaker>
  +craft, making it easier to extend the autogenerated I<Makefile> with
  +the C<Apache::Test>
  +
  +=head1 FUNCTIONS
  +
  +=head2 C<import>
  +
  +  use Apache::TestMM qw(test clean);
  +
  +or:
  +
  +  Apache::TestMM->import(qw(test clean));
  +
  +imports C<MY::> overrides for the default C<ExtUtils::MakeMaker>
  +I<test> and I<clean> targets, as if you have defined:
  +
  +  sub MY::test {...}
  +  sub MY::clean {...}
  +
  +in I<Makefile.PL>. C<Apache::TestMM> does this for you.
  +
  +=head2 C<filter_args>
  +
  +  push @ARGV, '-apxs', $apxs_path;
  +  Apache::TestMM::filter_args();
  +  WriteMakefile(...);
  +
  +As you know when C<WriteMakefile()> is called it parses C<@ARGV>
  +hoping to find special options like C<PREFIX=/home/stas/perl>. On the
  +other hand C<Apache::Test> accepts a lot of options of its own. When
  +C<Apache::TestMM::filter_args()> is called, it removes any
  +C<Apache::Test> specific options from C<@ARGV> and stores them
  +internally, so when C<WriteMakefile()> is called they aren't in
  +C<ARGV>.
  +
  +The options can be set when I<Makefile.PL> is called:
  +
  +  % perl Makefile.PL -apxs /path/to/apxs
  +
  +or you can push them manually to C<@ARGV> from the code:
  +
  +  push @ARGV, '-apxs', $apxs_path;
  +
  +When:
  +
  +  Apache::TestMM::generate_script('t/TEST');
  +
  +is called, C<Apache::Test> specific options which were extracted by
  +C<Apache::TestMM::filter_args()> are written to the autogenerated
  +file. In our example the autogenerated I<t/TEST> will include:
  +
  +  %Apache::TestConfig::Argv = qw(apxs /path/to/apxs);
  +
  +which is going to be used by the C<Apache::Test> runtime.
  +
  +=head2 C<generate_script>
  +
  +  Apache::TestMM::generate_script('t/TEST');
  +
  +C<generate_script()> accepts the name of the script to generate and
  +will look for a template with the same name and suffix I<.PL>. So in
  +our example it'll look for I<t/TEST.PL>. The autogenerated script
  +I<t/TEST> will include the contents of I<t/TEST.PL>, and special
  +directives, including any configuration options passed via
  +C<L<filter_args()|/C_filter_args_>> called from I<Makefile.PL>, special
  +fixup code, etc.
  +
  +=cut