=head1 NAME

ModPerl::MM -- A "subclass" of ExtUtils::MakeMaker for mod_perl 2.0

=head1 Synopsis

  use ModPerl::MM;
  
  # ModPerl::MM takes care of doing all the dirty job of overriding 
  ModPerl::MM::WriteMakefile(...);

  # if there is a need to extend the default methods 
  sub MY::constants {
      my $self = shift;
      $self->ModPerl::MM::MY::constants;
      # do something else;
  }

  # or prevent overriding completely
  sub MY::constants { shift->MM::constants(@_); }";

  # override the default value of WriteMakefile's attribute
  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => $extra_inc,
      ...
  );

  # extend the default value of WriteMakefile's attribute
  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt('INC'),
      ...
  );

=head1 Description

C<ModPerl::MM> is a "subclass" of C<ExtUtils::MakeMaker> for mod_perl
2.0, to a degree of sub-classability of C<ExtUtils::MakeMaker>. 

When C<ModPerl::MM::WriteMakefile()> is used instead of
C<ExtUtils::MakeMaker::WriteMakefile()>, C<ModPerl::MM> overrides
several C<ExtUtils::MakeMaker> methods behind the scenes and supplies
default C<WriteMakefile()> arguments adjusted for mod_perl 2.0
build. It's written in such a way so that normally 3rd party module
developers for mod_perl 2.0, don't need to mess with I<Makefile.PL> at
all.

=head1 C<MY::> Default Methods

C<ModPerl::MM> overrides method I<foo> as long as I<Makefile.PL>
hasn't already specified a method I<MY::foo>. If the latter happens,
C<ModPerl::MM> will DWIM and do nothing.

In case the functionality of C<ModPerl::MM> methods needs to be
extended, rather than completely overriden, the C<ModPerl::MM> methods
can be called internally. For example if you need to modify constants
in addition to the modifications applied by
C<ModPerl::MM::MY::constants>, call the C<ModPerl::MM::MY::constants>
method (notice that it resides in the package C<ModPerl::MM::MY> and
not C<ModPerl::MM>), then do your extra manipulations on constants:

  # if there is a need to extend the methods 
  sub MY::constants {
      my $self = shift;
      $self->ModPerl::MM::MY::constants;
      # do something else;
  }

In certain cases a developers may want to prevent from C<ModPerl::MM>
to override certain methods. In that case an explicit override in
I<Makefile.PL> will do the job. For example if you don't want the
C<constants()> method to be overriden by C<ModPerl::MM>, add to your
I<Makefile.PL>:

  sub MY::constants { shift->MM::constants(@_); }";

C<ModPerl::MM> overrides the following methods:

=head2 C<ModPerl::MM::MY::post_initialize>

This method is deprecated.

=head1 C<WriteMakefile()> Default Arguments

C<ModPerl::MM::WriteMakefile> supplies default arguments such as
C<INC> and C<TYPEMAPS> unless they weren't passed to
C<ModPerl::MM::WriteMakefile> from I<Makefile.PL>.

If the default values aren't satisfying these should be overriden in
I<Makefile.PL>. For example to supply an empty INC, explicitly set the
argument in I<Makefile.PL>.

  ModPerl::MM::WriteMakefile(
      ...
      INC => '',
      ...
  );

If instead of fully overriding the default arguments, you want to
extend or modify them, they can be retrieved using the
C<ModPerl::MM::get_def_opt()> function. The following example appends
an extra value to the default C<INC> attribute:

  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt('INC'),
      ...
  );

C<ModPerl::MM> supplies default values for the following
C<ModPerl::MM::WriteMakefile> attributes:

=head2 C<CCFLAGS>


=head2 C<LIBS>


=head2 C<INC>


=head2 C<OPTIMIZE>


=head2 C<LDDLFLAGS>


=head2 C<TYPEMAPS>


=head2 C<dynamic_lib>

=head3 C<OTHERLDFLAGS>

  dynamic_lib => { OTHERLDFLAGS => ... }

=head2 C<macro>

=head3 C<MOD_INSTALL>

  macro => { MOD_INSTALL => ... }

makes sure that Apache-Test/ is added to @INC.

=head1 Public API

The following functions are a part of the public API. They are
described elsewhere in this document.

=head2 C<WriteMakefile()>

  ModPerl::MM::WriteMakefile(...);

=head2 C<get_def_opt()>

  my $def_val = ModPerl::MM::get_def_opt($key);

=cut