The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

GOZER / mod_perl-2.0.0-RC2-XMas / docs / api / ModPerl / MM.pod 

            

              
—
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

              
=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::constants>
This method makes sure that everything gets installed relative to the
C<Apache2/> subdir if C<MP_INST_APACHE2=1> was used to build mod_perl
2.0.
=head2 C<ModPerl::MM::MY::post_initialize>
This method makes sure that everything gets installed relative to the
C<Apache2/> subdir if C<MP_INST_APACHE2=1> was used to build mod_perl
2.0.
=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 => ... }
arranges for modules to be installed under the subdir I<Apache2/> if
mod_perl was built with C<MP_INST_APACHE2=1>.
=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