.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "docs::api::ModPerl::MM 3pm"
.TH docs::api::ModPerl::MM 3pm 2024-03-29 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
ModPerl::MM \-\- A "subclass" of ExtUtils::MakeMaker for mod_perl 2.0
.SH Synopsis
.IX Header "Synopsis"
.Vb 1
\&  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\*(Aqs attribute
\&  my $extra_inc = "/foo/include";
\&  ModPerl::MM::WriteMakefile(
\&      ...
\&      INC => $extra_inc,
\&      ...
\&  );
\&
\&  # extend the default value of WriteMakefile\*(Aqs attribute
\&  my $extra_inc = "/foo/include";
\&  ModPerl::MM::WriteMakefile(
\&      ...
\&      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt(\*(AqINC\*(Aq),
\&      ...
\&  );
.Ve
.SH Description
.IX Header "Description"
\&\f(CW\*(C`ModPerl::MM\*(C'\fR is a "subclass" of \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR for mod_perl
2.0, to a degree of sub-classability of \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR.
.PP
When \f(CWModPerl::MM::WriteMakefile()\fR is used instead of
\&\f(CWExtUtils::MakeMaker::WriteMakefile()\fR, \f(CW\*(C`ModPerl::MM\*(C'\fR overrides
several \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR methods behind the scenes and supplies
default \f(CWWriteMakefile()\fR 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 \fIMakefile.PL\fR at
all.
.ie n .SH """MY::"" Default Methods"
.el .SH "\f(CWMY::\fP Default Methods"
.IX Header "MY:: Default Methods"
\&\f(CW\*(C`ModPerl::MM\*(C'\fR overrides method \fIfoo\fR as long as \fIMakefile.PL\fR
hasn't already specified a method \fIMY::foo\fR. If the latter happens,
\&\f(CW\*(C`ModPerl::MM\*(C'\fR will DWIM and do nothing.
.PP
In case the functionality of \f(CW\*(C`ModPerl::MM\*(C'\fR methods needs to be
extended, rather than completely overridden, the \f(CW\*(C`ModPerl::MM\*(C'\fR methods
can be called internally. For example if you need to modify constants
in addition to the modifications applied by
\&\f(CW\*(C`ModPerl::MM::MY::constants\*(C'\fR, call the \f(CW\*(C`ModPerl::MM::MY::constants\*(C'\fR
method (notice that it resides in the package \f(CW\*(C`ModPerl::MM::MY\*(C'\fR and
not \f(CW\*(C`ModPerl::MM\*(C'\fR), then do your extra manipulations on constants:
.PP
.Vb 6
\&  # if there is a need to extend the methods 
\&  sub MY::constants {
\&      my $self = shift;
\&      $self\->ModPerl::MM::MY::constants;
\&      # do something else;
\&  }
.Ve
.PP
In certain cases a developers may want to prevent from \f(CW\*(C`ModPerl::MM\*(C'\fR
to override certain methods. In that case an explicit override in
\&\fIMakefile.PL\fR will do the job. For example if you don't want the
\&\f(CWconstants()\fR method to be overridden by \f(CW\*(C`ModPerl::MM\*(C'\fR, add to your
\&\fIMakefile.PL\fR:
.PP
.Vb 1
\&  sub MY::constants { shift\->MM::constants(@_); }";
.Ve
.PP
\&\f(CW\*(C`ModPerl::MM\*(C'\fR overrides the following methods:
.ie n .SS """ModPerl::MM::MY::post_initialize"""
.el .SS \f(CWModPerl::MM::MY::post_initialize\fP
.IX Subsection "ModPerl::MM::MY::post_initialize"
This method is deprecated.
.ie n .SH "WriteMakefile() Default Arguments"
.el .SH "\f(CWWriteMakefile()\fP Default Arguments"
.IX Header "WriteMakefile() Default Arguments"
\&\f(CW\*(C`ModPerl::MM::WriteMakefile\*(C'\fR supplies default arguments such as
\&\f(CW\*(C`INC\*(C'\fR and \f(CW\*(C`TYPEMAPS\*(C'\fR unless they weren't passed to
\&\f(CW\*(C`ModPerl::MM::WriteMakefile\*(C'\fR from \fIMakefile.PL\fR.
.PP
If the default values aren't satisfying these should be overridden in
\&\fIMakefile.PL\fR. For example to supply an empty INC, explicitly set the
argument in \fIMakefile.PL\fR.
.PP
.Vb 5
\&  ModPerl::MM::WriteMakefile(
\&      ...
\&      INC => \*(Aq\*(Aq,
\&      ...
\&  );
.Ve
.PP
If instead of fully overriding the default arguments, you want to
extend or modify them, they can be retrieved using the
\&\f(CWModPerl::MM::get_def_opt()\fR function. The following example appends
an extra value to the default \f(CW\*(C`INC\*(C'\fR attribute:
.PP
.Vb 6
\&  my $extra_inc = "/foo/include";
\&  ModPerl::MM::WriteMakefile(
\&      ...
\&      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt(\*(AqINC\*(Aq),
\&      ...
\&  );
.Ve
.PP
\&\f(CW\*(C`ModPerl::MM\*(C'\fR supplies default values for the following
\&\f(CW\*(C`ModPerl::MM::WriteMakefile\*(C'\fR attributes:
.ie n .SS """CCFLAGS"""
.el .SS \f(CWCCFLAGS\fP
.IX Subsection "CCFLAGS"
.ie n .SS """LIBS"""
.el .SS \f(CWLIBS\fP
.IX Subsection "LIBS"
.ie n .SS """INC"""
.el .SS \f(CWINC\fP
.IX Subsection "INC"
.ie n .SS """OPTIMIZE"""
.el .SS \f(CWOPTIMIZE\fP
.IX Subsection "OPTIMIZE"
.ie n .SS """LDDLFLAGS"""
.el .SS \f(CWLDDLFLAGS\fP
.IX Subsection "LDDLFLAGS"
.ie n .SS """TYPEMAPS"""
.el .SS \f(CWTYPEMAPS\fP
.IX Subsection "TYPEMAPS"
.ie n .SS """dynamic_lib"""
.el .SS \f(CWdynamic_lib\fP
.IX Subsection "dynamic_lib"
\fR\f(CI\*(C`OTHERLDFLAGS\*(C'\fR\fI\fR
.IX Subsection "OTHERLDFLAGS"
.PP
.Vb 1
\&  dynamic_lib => { OTHERLDFLAGS => ... }
.Ve
.ie n .SS """macro"""
.el .SS \f(CWmacro\fP
.IX Subsection "macro"
\fR\f(CI\*(C`MOD_INSTALL\*(C'\fR\fI\fR
.IX Subsection "MOD_INSTALL"
.PP
.Vb 1
\&  macro => { MOD_INSTALL => ... }
.Ve
.PP
makes sure that Apache\-Test/ is added to \f(CW@INC\fR.
.SH "Public API"
.IX Header "Public API"
The following functions are a part of the public API. They are
described elsewhere in this document.
.ie n .SS WriteMakefile()
.el .SS \f(CWWriteMakefile()\fP
.IX Subsection "WriteMakefile()"
.Vb 1
\&  ModPerl::MM::WriteMakefile(...);
.Ve
.ie n .SS get_def_opt()
.el .SS \f(CWget_def_opt()\fP
.IX Subsection "get_def_opt()"
.Vb 1
\&  my $def_val = ModPerl::MM::get_def_opt($key);
.Ve