You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by ra...@apache.org on 2005/04/03 03:04:11 UTC
svn commit: r159855 - in perl/modperl/docs/trunk/src/docs/2.0/user/porting:
compat.pod porting.pod
Author: randyk
Date: Sat Apr 2 17:04:11 2005
New Revision: 159855
URL: http://svn.apache.org/viewcvs?view=rev&rev=159855
Log:
s/Apache/Apache2/, and also remove the discussion about this
renaming.
Modified:
perl/modperl/docs/trunk/src/docs/2.0/user/porting/compat.pod
perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/porting/compat.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/porting/compat.pod?view=diff&r1=159854&r2=159855
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/porting/compat.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/porting/compat.pod Sat Apr 2 17:04:11 2005
@@ -18,7 +18,7 @@
about L<porting XS modules|docs::2.0::devel::porting::porting>).
As it will be explained in details later, loading
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> at the server
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> at the server
startup, should make the code running properly under 1.0 work under
mod_perl 2.0. If you want to port your code to mod_perl 2.0 or writing
from scratch and not concerned about backwards compatibility, this
@@ -131,7 +131,7 @@
=head2 C<$Apache::Server::StrictPerlSections>
In mod_perl 2.0, C<L<E<lt>PerlE<gt>
-sections|docs::2.0::api::Apache::PerlSections>> errors are now always
+sections|docs::2.0::api::Apache2::PerlSections>> errors are now always
fatal. Any error in them will cause an immediate server startup abort,
dumping the error to STDERR. To avoid this, C<eval {}> can be used to
trap errors and ignore them. In mod_perl 1.0, C<strict> was somewhat
@@ -143,8 +143,8 @@
=head2 C<$Apache::Server::SaveConfig>
C<$Apache::Server::SaveConfig> has been renamed to
-C<$Apache::PerlSections::Save>. see C<L<E<lt>PerlE<gt>
-sections|docs::2.0::api::Apache::PerlSections>> for more information
+C<$Apache2::PerlSections::Save>. see C<L<E<lt>PerlE<gt>
+sections|docs::2.0::api::Apache2::PerlSections>> for more information
on this global variable.
@@ -212,7 +212,7 @@
gain a complete compatibilty with 1.0 while running under 2.0, you
should load the compatibility module as early as possible:
- use Apache::compat;
+ use Apache2::compat;
at the server startup. And unless there are forgotten things or bugs,
your code should work without any changes under 2.0 series.
@@ -225,44 +225,6 @@
This document explains what APIs have changed and what new APIs should
be used instead.
-If you have mod_perl 1.0 and 2.0 installed on the same system and the
-two use the same perl libraries directory (e.g. I</usr/lib/perl5>), to
-use mod_perl 2.0 make sure to load first the C<Apache2> module which
-will perform the necessary adjustments to C<@INC>.
-
- use Apache2; # if you have 1.0 and 2.0 installed
- use Apache::compat;
-
-So if before loading C<Apache2.pm> the C<@INC> array consisted of:
-
- /home/stas/perl/ithread/lib/5.8.0/i686-linux-thread-multi
- /home/stas/perl/ithread/lib/5.8.0
- /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi
- /home/stas/perl/ithread/lib/site_perl/5.8.0
- /home/stas/perl/ithread/lib/site_perl
- .
-
-It will now look as:
-
- /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi/Apache2
- /home/stas/perl/ithread/lib/5.8.0/i686-linux-thread-multi
- /home/stas/perl/ithread/lib/5.8.0
- /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi
- /home/stas/perl/ithread/lib/site_perl/5.8.0
- /home/stas/perl/ithread/lib/site_perl
- .
-
-Notice that a new directory was prepended to the search path, so if
-for example the code attempts to load C<Apache::RequestRec> and there
-are two versions of this module undef
-I</home/stas/perl/ithread/lib/site_perl/>:
-
- 5.8.0/i686-linux-thread-multi/Apache/RequestRec.pm
- 5.8.0/i686-linux-thread-multi/Apache2/Apache/RequestRec.pm
-
-The mod_perl 2.0 version will be loaded first, because the directory
-I<5.8.0/i686-linux-thread-multi/Apache2> is coming before the
-directory I<5.8.0/i686-linux-thread-multi> in C<@INC>.
Finally, mod_perl 2.0 has all its methods spread across many
modules. In order to use these methods the modules containing them
@@ -292,7 +254,7 @@
C<Apache::Registry>, C<Apache::PerlRun> and other modules from the
registry family now live in the C<ModPerl::> namespace. In mod_perl
2.0 we put mod_perl specific functionality into the C<ModPerl::>
-namespace, similar to C<APR::> and C<Apache::> which are used for apr
+namespace, similar to C<APR::> and C<Apache2::> which are used for apr
and apache features, respectively.
At this moment
@@ -385,7 +347,7 @@
=over
-=item C<L<Apache::Const|docs::2.0::api::Apache::Const>>
+=item C<L<Apache2::Const|docs::2.0::api::Apache2::Const>>
Apache constants
@@ -404,7 +366,7 @@
META: add the info how to perform the transition. XXX: may be write a
script, which can tell you how to port the constants to 2.0? Currently
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> doesn't provide a
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> doesn't provide a
complete back compatibility layer.
@@ -420,7 +382,7 @@
If the same codebase is used for both mod_perl generations, the
following technique can be used for using constants:
- package MyApache::Foo;
+ package MyApache2::Foo;
use strict;
use warnings;
@@ -430,8 +392,8 @@
BEGIN {
if (MP2) {
- require Apache::Const;
- Apache::Const->import(-compile => qw(OK DECLINED));
+ require Apache2::Const;
+ Apache2::Const->import(-compile => qw(OK DECLINED));
}
else {
require Apache::Constants;
@@ -441,13 +403,13 @@
sub handler {
# ...
- return MP2 ? Apache::OK : Apache::Constants::OK;
+ return MP2 ? Apache2::OK : Apache::Constants::OK;
}
1;
Notice that if you don't use the idiom:
- return MP2 ? Apache::OK : Apache::Constants::OK;
+ return MP2 ? Apache2::OK : Apache::Constants::OK;
but something like the following:
@@ -457,7 +419,7 @@
}
sub handler2 {
...
- return Apache::OK();
+ return Apache2::OK();
}
You need to add C<()>. If you don't do that, let's say that you run
@@ -502,7 +464,7 @@
=head2 C<SERVER_VERSION()>
C<Apache::Constants::SERVER_VERSION()> has been replaced with
-C<L<Apache::ServerUtil::get_server_version()|docs::2.0::api::Apache::ServerUtil/C_get_server_version_>>.
+C<L<Apache2::ServerUtil::get_server_version()|docs::2.0::api::Apache2::ServerUtil/C_get_server_version_>>.
@@ -586,7 +548,7 @@
=head2 C<Apache-E<gt>request>
-C<L<Apache-E<gt>request|docs::2.0::api::Apache::RequestUtil/C_request_>>
+C<L<Apache-E<gt>request|docs::2.0::api::Apache2::RequestUtil/C_request_>>
usage should be avoided under mod_perl 2.0 C<$r> should be passed
around as an argument instead (or in the worst case maintain your own
global variable). Since your application may run under under threaded
@@ -607,7 +569,7 @@
sub handler {
print "Content-type: text/plain\n\n";
print "Hello";
- return Apache::OK;
+ return Apache2::OK;
}
where the C<handler()> function always receives C<$r> as an argument,
@@ -636,7 +598,7 @@
print "Content-type: text/plain\n\n";
}
print "Hello"
- return Apache::OK;
+ return Apache2::OK;
}
The script works under both mod_perl and mod_cgi.
@@ -671,16 +633,16 @@
following skeleton for an I<authen> phase handler makes the
C<Apache-E<gt>request> available in the calls made from it:
- package MyApache::Auth;
+ package MyApache2::Auth;
- # PerlAuthenHandler MyApache::Auth
+ # PerlAuthenHandler MyApache2::Auth
- use Apache::RequestUtil ();
+ use Apache2::RequestUtil ();
#...
sub handler {
my $r = shift;
- Apache->request($r);
- # do some calls that rely on Apache->request being available
+ Apache2->request($r);
+ # do some calls that rely on Apache2->request being available
#...
}
@@ -692,7 +654,7 @@
=head2 C<Apache-E<gt>define>
C<Apache-E<gt>define> has been replaced with
-C<L<Apache::ServerUtil::exists_config_define()|docs::2.0::api::Apache::ServerUtil/C_exists_config_define_>>.
+C<L<Apache2::ServerUtil::exists_config_define()|docs::2.0::api::Apache2::ServerUtil/C_exists_config_define_>>.
@@ -710,13 +672,13 @@
=head2 C<Apache-E<gt>untaint>
C<Apache-E<gt>untaint> has moved to
-C<L<Apache::ModPerl::Util::untaint()|docs::2.0::api::ModPerl::Util/C_untaint_>>
+C<L<Apache2::ModPerl::Util::untaint()|docs::2.0::api::ModPerl::Util/C_untaint_>>
and now is a function, rather a class method. It'll will untaint all
its arguments. You shouldn't be using this function unless you know
what you are doing. Refer to the I<perlsec> manpage for more
information.
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> provides the
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> provides the
backward compatible with mod_perl 1.0 implementation.
@@ -726,38 +688,38 @@
=head2 C<Apache-E<gt>get_handlers>
To get handlers for the server level, mod_perl 2.0 code should use
-C<L<Apache::ServerUtil::get_handlers()|docs::2.0::api::Apache::ServerUtil/C_get_handlers_>>:
+C<L<Apache2::ServerUtil::get_handlers()|docs::2.0::api::Apache2::ServerUtil/C_get_handlers_>>:
$s->get_handlers(...);
or:
- Apache->server->get_handlers(...);
+ Apache2->server->get_handlers(...);
C<Apache-E<gt>get_handlers> is avalable via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
See also
-C<L<Apache::RequestUtil::get_handlers()|docs::2.0::api::Apache::RequestUtil/C_get_handlers_>>.
+C<L<Apache2::RequestUtil::get_handlers()|docs::2.0::api::Apache2::RequestUtil/C_get_handlers_>>.
=head2 C<Apache-E<gt>push_handlers>
To push handlers at the server level, mod_perl 2.0 code should use
-C<L<Apache::ServerUtil::push_handlers()|docs::2.0::api::Apache::ServerUtil/C_push_handlers_>>:
+C<L<Apache2::ServerUtil::push_handlers()|docs::2.0::api::Apache2::ServerUtil/C_push_handlers_>>:
$s->push_handlers(...);
or:
- Apache->server->push_handlers(...);
+ Apache2->server->push_handlers(...);
C<Apache-E<gt>push_handlers> is avalable via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
See also
-C<L<Apache::RequestUtil::push_handlers()|docs::2.0::api::Apache::RequestUtil/C_push_handlers_>>.
+C<L<Apache2::RequestUtil::push_handlers()|docs::2.0::api::Apache2::RequestUtil/C_push_handlers_>>.
@@ -765,16 +727,16 @@
=head2 C<Apache-E<gt>set_handlers>
To set handlers at the server level, mod_perl 2.0 code should use
-C<L<Apache::ServerUtil::set_handlers()|docs::2.0::api::Apache::ServerUtil/C_set_handlers_>>:
+C<L<Apache2::ServerUtil::set_handlers()|docs::2.0::api::Apache2::ServerUtil/C_set_handlers_>>:
$s->set_handlers(...);
or:
- Apache->server->set_handlers(...);
+ Apache2->server->set_handlers(...);
C<Apache-E<gt>set_handlers> is avalable via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
To reset the list of handlers, instead of doing:
@@ -789,7 +751,7 @@
$r->set_handlers(PerlAuthenHandler => undef);
See also
-C<L<Apache::RequestUtil::set_handlers()|docs::2.0::api::Apache::RequestUtil/C_set_handlers_>>.
+C<L<Apache2::RequestUtil::set_handlers()|docs::2.0::api::Apache2::RequestUtil/C_set_handlers_>>.
@@ -799,16 +761,16 @@
=head2 C<Apache-E<gt>httpd_conf>
C<Apache-E<gt>httpd_conf> is now
-C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_add_config_>>:
+C<L<$s-E<gt>add_config|docs::2.0::api::Apache2::ServerUtil/C_add_config_>>:
- require Apache::ServerUtil;
- Apache->server->add_config(['require valid-user']);
+ require Apache2::ServerUtil;
+ Apache2->server->add_config(['require valid-user']);
C<Apache-E<gt>httpd_conf> is avalable via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
See also
-C<L<Apache::RequestUtil::add_config()|docs::2.0::api::Apache::RequestUtil/C_add_config_>>.
+C<L<Apache2::RequestUtil::add_config()|docs::2.0::api::Apache2::RequestUtil/C_add_config_>>.
@@ -821,7 +783,7 @@
(http://search.cpan.org/dist/CGI.pm/CGI/Util.pm).
It is also available via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>
for backwards compatibility.
@@ -856,12 +818,12 @@
C<Apache::log_error()> is not available in mod_perl 2.0 API. You can
use
-C<L<Apache::Log::log_error()|docs::2.0::api::Apache::Log/C__s_E_gt_log_error_>>:
+C<L<Apache2::Log::log_error()|docs::2.0::api::Apache2::Log/C__s_E_gt_log_error_>>:
- Apache->server->log_error
+ Apache2->server->log_error
instead. See the
-C<L<Apache::Log|docs::2.0::api::Apache::Log>> manpage.
+C<L<Apache2::Log|docs::2.0::api::Apache2::Log>> manpage.
@@ -870,8 +832,8 @@
=head2 C<Apache-E<gt>warn>
C<$Apache-E<gt>warn> has been removed and exists only in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>. Choose another
-C<L<Apache::Log|docs::2.0::api::Apache::Log>> method.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>. Choose another
+C<L<Apache2::Log|docs::2.0::api::Apache2::Log>> method.
@@ -879,15 +841,15 @@
=head2 C<Apache::warn>
C<$Apache::warn> has been removed and exists only in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>. Choose another
-C<L<Apache::Log|docs::2.0::api::Apache::Log>> method.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>. Choose another
+C<L<Apache2::Log|docs::2.0::api::Apache2::Log>> method.
=head2 C<Apache::module()>
C<Apache::module()> has been replaced with the function
-C<L<Apache::Module::loaded()|docs::2.0::api::Apache::Module/C_loaded_>>,
+C<L<Apache2::Module::loaded()|docs::2.0::api::Apache2::Module/C_loaded_>>,
which now accepts a single argument: the module name.
@@ -920,14 +882,14 @@
=head2 C<Apache::Module-E<gt>top_module>
C<Apache::Module-E<gt>top_module> has been replaced with the function
-C<L<Apache::Module::top_module()|docs::2.0::api::Apache::Module/C_top_module_>>.
+C<L<Apache2::Module::top_module()|docs::2.0::api::Apache2::Module/C_top_module_>>.
=head2 C<Apache::Module-E<gt>get_config>
C<Apache::Module-E<gt>get_config> has been replaced with the function
-C<L<Apache::Module::get_config()|docs::2.0::api::Apache::Module/C_get_config_>>.
+C<L<Apache2::Module::get_config()|docs::2.0::api::Apache2::Module/C_get_config_>>.
@@ -944,7 +906,7 @@
=head2 C<Apache::ModuleConfig-E<gt>get>
C<Apache::ModuleConfig-E<gt>get> has been replaced with the function
-C<L<Apache::Module::get_config()|docs::2.0::api::Apache::Module/C_get_config_>>.
+C<L<Apache2::Module::get_config()|docs::2.0::api::Apache2::Module/C_get_config_>>.
@@ -960,7 +922,7 @@
=head2 C<$Apache::Server::CWD>
C<$Apache::Server::CWD> is deprecated and exists only in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
@@ -968,7 +930,7 @@
=head2 C<$Apache::Server::AddPerlVersion>
C<$Apache::Server::AddPerlVersion> is deprecated and exists only in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
@@ -977,8 +939,8 @@
C<$Apache::Server::Starting> and C<$Apache::Server::ReStarting> were
replaced by
-C<L<Apache::ServerUtil::restart_count()|docs::2.0::api::Apache::ServerUtil/C_restart_count_>>.
-Though both exist in C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::ServerUtil::restart_count()|docs::2.0::api::Apache2::ServerUtil/C_restart_count_>>.
+Though both exist in C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
@@ -986,8 +948,8 @@
=head2 C<Apache::Server-E<gt>warn>
C<Apache::Server-E<gt>warn> has been removed and exists only in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>. Choose another
-C<L<Apache::Log|docs::2.0::api::Apache::Log>> method.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>. Choose another
+C<L<Apache2::Log|docs::2.0::api::Apache2::Log>> method.
@@ -1007,11 +969,11 @@
which accepts the pool object as the first argument instead of the
server object. e.g.:
- use Apache::ServerUtil ();
+ use Apache2::ServerUtil ();
sub cleanup_callback {
my($pool, $s) = @_;
# your code comes here
- Apache::OK;
+ Apache2::OK;
}
$s->push_handlers(PerlChildExitHandler => \&my_access);
@@ -1023,7 +985,7 @@
In order to register a cleanup handler to be run only once when the
main server (not each child process) shuts down, you can register a
cleanup handler with
-C<L<server_shutdown_cleanup_register()|docs::2.0::api::Apache::ServerUtil/C_server_shutdown_cleanup_register_>>.
+C<L<server_shutdown_cleanup_register()|docs::2.0::api::Apache2::ServerUtil/C_server_shutdown_cleanup_register_>>.
@@ -1043,8 +1005,8 @@
It's possible to emulate mod_perl 1.0 API doing:
- sub Apache::Server::uid { $< }
- sub Apache::Server::gid { $( }
+ sub Apache2::Server::uid { $< }
+ sub Apache2::Server::gid { $( }
but the problem is that if the server is started as I<root>, but its
child processes are run under a different username, e.g. I<nobody>, at
@@ -1074,7 +1036,7 @@
=head2 C<$r-E<gt>cgi_var>
C<$r-E<gt>cgi_env> and C<$r-E<gt>cgi_var> should be replaced with
-C<L<$r-E<gt>subprocess_env|docs::2.0::api::Apache::RequestRec/C_subprocess_env_>>,
+C<L<$r-E<gt>subprocess_env|docs::2.0::api::Apache2::RequestRec/C_subprocess_env_>>,
which works identically in both mod_perl generations.
@@ -1086,7 +1048,7 @@
and can be called for any of the phases, including those where C<$r>
simply doesn't exist.
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> implements
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> implements
C<$r-E<gt>current_callback> for backwards compatibility.
@@ -1095,30 +1057,30 @@
=head2 C<$r-E<gt>cleanup_for_exec>
C<$r-E<gt>cleanup_for_exec> wasn't a part of the mp1 core API, but
-lived in a 3rd party module C<Apache::SubProcess>. That module's
+lived in a 3rd party module C<Apache2::SubProcess>. That module's
functionality is now a part of mod_perl 2.0 API. But Apache 2.0
doesn't need this function any longer.
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> implements
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> implements
C<$r-E<gt>cleanup_for_exec> for backwards compatibility as a NOOP.
See also the
-C<L<Apache::SubProcess|docs::2.0::api::Apache::SubProcess>> manpage.
+C<L<Apache2::SubProcess|docs::2.0::api::Apache2::SubProcess>> manpage.
=head2 C<$r-E<gt>get_remote_host>
-C<L<get_remote_host()|docs::2.0::api::Apache::Connection/C_get_remote_host_>>
+C<L<get_remote_host()|docs::2.0::api::Apache2::Connection/C_get_remote_host_>>
is now invoked on the C<L<connection
-object|docs::2.0::api::Apache::Connection>>:
+object|docs::2.0::api::Apache2::Connection>>:
- use Apache::Connection;
+ use Apache2::Connection;
$r->connection->get_remote_host();
C<$r-E<gt>get_remote_host> is available through
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
@@ -1131,7 +1093,7 @@
=head2 C<$r-E<gt>args> in an Array Context
-C<L<$r-E<gt>args|docs::2.0::api::Apache::RequestRec/C_args_>> in 2.0
+C<L<$r-E<gt>args|docs::2.0::api::Apache2::RequestRec/C_args_>> in 2.0
returns the query string without parsing and splitting it into an
array. You can also set the query string by passing a string to this
method.
@@ -1173,7 +1135,7 @@
=back
For now you can use C<CGI.pm> or the code in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> (it's slower).
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> (it's slower).
META: when C<Apache::Request> will be ported to mod_perl 2.0, you will
have the fast C implementation of these functions.
@@ -1199,11 +1161,11 @@
=head2 C<$r-E<gt>is_main>
C<$r-E<gt>is_main> is not part of the mod_perl 2.0 API. Use
-C<L<!$r-E<gt>main|docs::2.0::api::Apache::RequestRec/C_main_>>
+C<L<!$r-E<gt>main|docs::2.0::api::Apache2::RequestRec/C_main_>>
instead.
Refer to the
-C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec/main__>>
+C<L<Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec/main__>>
manpage.
@@ -1211,13 +1173,13 @@
=head2 C<$r-E<gt>filename>
When a new
-C<L<$r-E<gt>filename|docs::2.0::api::Apache::RequestRec/C_filename_>>
+C<L<$r-E<gt>filename|docs::2.0::api::Apache2::RequestRec/C_filename_>>
is assigned Apache 2.0 doesn't update the finfo structure like it did
-in Apache 1.3. If the old behavior is desired Apache::compat's
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>
+in Apache 1.3. If the old behavior is desired Apache2::compat's
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>
can be used. Otherwise one should explicitly update the finfo struct
when desired as explained in the
-C<L<filename|docs::2.0::api::Apache::RequestRec/C_filename_>> API
+C<L<filename|docs::2.0::api::Apache2::RequestRec/C_filename_>> API
entry.
@@ -1234,14 +1196,14 @@
methods on it.
It's also possible to adjust the mod_perl 1.0 code using
-Apache::compat's
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
+Apache2::compat's
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
For example:
- use Apache::compat;
- Apache::compat::override_mp2_api('Apache::RequestRec::finfo');
+ use Apache2::compat;
+ Apache2::compat::override_mp2_api('Apache2::RequestRec::finfo');
my $is_writable = -w $r->finfo;
- Apache::compat::restore_mp2_api('Apache::RequestRec::finfo');
+ Apache2::compat::restore_mp2_api('Apache2::RequestRec::finfo');
which internally does just the following:
@@ -1256,7 +1218,7 @@
don't want this extra call, you'd have to write:
use APR::Finfo;
- use Apache::RequestRec;
+ use Apache2::RequestRec;
use APR::Const -compile => qw(WWRITE);
my $is_writable = $r->finfo->protection & APR::WWRITE,
@@ -1269,11 +1231,11 @@
=head2 C<$r-E<gt>notes>
Similar to
-C<L<headers_in()|docs::2.0::api::Apache::RequestRec/C_headers_in_>>,
-C<L<headers_out()|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
+C<L<headers_in()|docs::2.0::api::Apache2::RequestRec/C_headers_in_>>,
+C<L<headers_out()|docs::2.0::api::Apache2::RequestRec/C_headers_out_>>
and
-C<L<err_headers_out()|docs::2.0::api::Apache::RequestRec/C_err_headers_out_>>
-in mod_perl 2.0, C<L<$r-E<gt>notes()|docs::2.0::api::Apache::RequestRec/C_notes_>> returns an
+C<L<err_headers_out()|docs::2.0::api::Apache2::RequestRec/C_err_headers_out_>>
+in mod_perl 2.0, C<L<$r-E<gt>notes()|docs::2.0::api::Apache2::RequestRec/C_notes_>> returns an
C<L<APR::Table|docs::2.0::api::APR::Table>> object, which can be used
as a tied hash or calling its
I<L<get()|docs::2.0::api::APR::Table/C_get_>> /
@@ -1282,16 +1244,16 @@
I<L<unset()|docs::2.0::api::APR::Table/C_unset_>> methods.
It's also possible to adjust the mod_perl 1.0 code using
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>'s
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>'s
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
- use Apache::compat;
- Apache::compat::override_mp2_api('Apache::RequestRec::notes');
+ use Apache2::compat;
+ Apache2::compat::override_mp2_api('Apache2::RequestRec::notes');
$r->notes($key => $val);
$val = $r->notes($key);
- Apache::compat::restore_mp2_api('Apache::RequestRec::notes');
+ Apache2::compat::restore_mp2_api('Apache2::RequestRec::notes');
-See the C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>
+See the C<L<Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec>>
manpage.
@@ -1313,10 +1275,10 @@
C<header_in()>, C<header_out()> and C<err_header_out()> are not
available in 2.0. Use
-C<L<headers_in()|docs::2.0::api::Apache::RequestRec/C_headers_in_>>,
-C<L<headers_out()|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
+C<L<headers_in()|docs::2.0::api::Apache2::RequestRec/C_headers_in_>>,
+C<L<headers_out()|docs::2.0::api::Apache2::RequestRec/C_headers_out_>>
and
-C<L<err_headers_out()|docs::2.0::api::Apache::RequestRec/C_err_headers_out_>>
+C<L<err_headers_out()|docs::2.0::api::Apache2::RequestRec/C_err_headers_out_>>
instead (which should be used in 1.0 as well). For example you need to
replace:
@@ -1326,7 +1288,7 @@
$r->err_headers_out->{'Pragma'} = "no-cache";
-See the L<Apache::RequestRec> manpage.
+See the L<Apache2::RequestRec> manpage.
@@ -1364,14 +1326,14 @@
=head2 C<$r-E<gt>request>
-Use C<L<Apache-E<gt>request|/C_Apache_E_gt_request_>>.
+Use C<L<Apache2-E<gt>request|/C_Apache2_E_gt_request_>>.
=head2 C<$r-E<gt>send_fd>
mod_perl 2.0 provides a new method
-C<L<sendfile()|docs::2.0::api::Apache::RequestIO/C_sendfile_>> instead
+C<L<sendfile()|docs::2.0::api::Apache2::RequestIO/C_sendfile_>> instead
of C<send_fd>, so if your code used to do:
open my $fh, "<$file" or die "$!";
@@ -1383,7 +1345,7 @@
$r->sendfile($file);
There is also a compatibility implementation of send_fd in pure perl
-in C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+in C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
XXX: later we may provide a direct access to the real send_fd. That
will be possible if we figure out how to portably convert PerlIO/FILE
@@ -1396,9 +1358,9 @@
=head2 C<$r-E<gt>send_http_header>
This method is not needed in 2.0, though available in
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>. 2.0 handlers only
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>. 2.0 handlers only
need to set the I<Content-type> via
-C<L<$r-E<gt>content_type($type)|docs::2.0::api::Apache::RequestRec/C_content_type_>>.
+C<L<$r-E<gt>content_type($type)|docs::2.0::api::Apache2::RequestRec/C_content_type_>>.
@@ -1406,13 +1368,13 @@
=head2 C<$r-E<gt>server_root_relative>
This method was replaced with
-C<L<Apache::ServerUtil::server_root_relative()|docs::2.0::api::Apache::ServerUtil/C_server_root_relative_>>
+C<L<Apache2::ServerUtil::server_root_relative()|docs::2.0::api::Apache2::ServerUtil/C_server_root_relative_>>
function and its first argument is a I<pool> object. For example:
# during request
- $conf_dir = Apache::server_root_relative($r->pool, 'conf');
+ $conf_dir = Apache2::server_root_relative($r->pool, 'conf');
# during startup
- $conf_dir = Apache::server_root_relative($s->pool, 'conf');
+ $conf_dir = Apache2::server_root_relative($s->pool, 'conf');
Note that the old form
@@ -1422,7 +1384,7 @@
passed a pool.
The old functionality is available with
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
@@ -1453,7 +1415,7 @@
The functions C<$r-E<gt>hard_timeout>, C<$r-E<gt>reset_timeout>,
C<$r-E<gt>soft_timeout> and C<$r-E<gt>kill_timeout> aren't needed in
-mod_perl 2.0. C<L<Apache::compat|docs::2.0::api::Apache::compat>>
+mod_perl 2.0. C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>
implements these functions for backwards compatibility as NOOPs.
@@ -1500,9 +1462,9 @@
The record I<auth_type> doesn't exist in the Apache 2.0's connection
struct. It exists only in the request record struct. The new accessor
in 2.0 API is
-C<L<$r-E<gt>ap_auth_type|docs::2.0::api::Apache::RequestRec/C_ap_auth_type_>>.
+C<L<$r-E<gt>ap_auth_type|docs::2.0::api::Apache2::RequestRec/C_ap_auth_type_>>.
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> provides a back
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> provides a back
compatibility method, though it relies on the availability of the
global C<Apache-E<gt>request>, which requires the configuration to
have:
@@ -1518,7 +1480,7 @@
=head2 C<$connection-E<gt>user>
This method is deprecated in mod_perl 1.0 and
-C<L<$r-E<gt>user|docs::2.0::api::Apache::RequestRec/C_user_>> should
+C<L<$r-E<gt>user|docs::2.0::api::Apache2::RequestRec/C_user_>> should
be used instead for both mod_perl generations. C<$r-E<gt>user()>
method is available since mod_perl version 1.24_01.
@@ -1534,9 +1496,9 @@
=head2 C<$connection-E<gt>remote_addr>
-C<L<$c-E<gt>local_addr|docs::2.0::api::Apache::Connection/C_local_addr_>>
+C<L<$c-E<gt>local_addr|docs::2.0::api::Apache2::Connection/C_local_addr_>>
and
-C<L<$c-E<gt>remote_addr|docs::2.0::api::Apache::Connection/C_remote_addr_>>
+C<L<$c-E<gt>remote_addr|docs::2.0::api::Apache2::Connection/C_remote_addr_>>
return an C<L<APR::SockAddr|docs::2.0::api::APR::SockAddr>> object and
you can use this object's methods to retrieve the wanted bits of
information, so if you had a code like:
@@ -1555,19 +1517,19 @@
my $remoteport = $c->remote_addr->port;
my $remoteip = $c->remote_addr->ip_get;
-It's also possible to adjust the code using Apache::compat's
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
+It's also possible to adjust the code using Apache2::compat's
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
use Socket 'sockaddr_in';
- use Apache::compat;
+ use Apache2::compat;
- Apache::compat::override_mp2_api('Apache::Connection::local_addr');
+ Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
my ($serverport, $serverip) = sockaddr_in($r->connection->local_addr);
- Apache::compat::restore_mp2_api('Apache::Connection::local_addr');
+ Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');
- Apache::compat::override_mp2_api('Apache::Connection::remote_addr');
+ Apache2::compat::override_mp2_api('Apache::Connection::remote_addr');
my ($remoteport, $remoteip) = sockaddr_in($r->connection->remote_addr);
- Apache::compat::restore_mp2_api('Apache::Connection::remote_addr');
+ Apache2::compat::restore_mp2_api('Apache::Connection::remote_addr');
@@ -1587,7 +1549,7 @@
The methods C<new()>, C<open()> and C<close()> were removed. See the
back compatibility implementation in the module
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
Because of that some of the idioms have changes too. If previously you
were writing:
@@ -1599,9 +1561,9 @@
close $fh;
Now, you would write that using
-C<L<Apache::RequestUtil::slurp_filename()|docs::2.0::api::Apache::RequestUtil/C_slurp_filename_>>:
+C<L<Apache2::RequestUtil::slurp_filename()|docs::2.0::api::Apache2::RequestUtil/C_slurp_filename_>>:
- use Apache::RequestUtil ();
+ use Apache2::RequestUtil ();
my $content = ${ $r->slurp_filename() };
@@ -1614,7 +1576,7 @@
API for this method anymore.
See C<File::Temp>, or the back compatibility implementation in the
-module C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
+module C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>.
With Perl v5.8.0 you can create anonymous temporary files:
@@ -1627,7 +1589,7 @@
=head1 C<Apache::Util>
-A few C<L<Apache::Util|docs::2.0::api::Apache::Util>> functions have
+A few C<L<Apache2::Util|docs::2.0::api::Apache2::Util>> functions have
changed their interface.
@@ -1644,17 +1606,17 @@
=head2 C<Apache::Util::escape_uri()>
C<Apache::Util::escape_uri()> has been replaced with
-C<L<Apache::Util::escape_path()|docs::2.0::api::Apache::Util/C_escape_path_>>
+C<L<Apache2::Util::escape_path()|docs::2.0::api::Apache2::Util/C_escape_path_>>
and requires a pool object as a second argument. For example:
- $escaped_path = Apache::Util::escape_path($path, $r->pool);
+ $escaped_path = Apache2::Util::escape_path($path, $r->pool);
=head2 C<Apache::Util::unescape_uri()>
C<Apache::Util::unescape_uri()> has been replaced with
-C<L<Apache::URI::unescape_url()|docs::2.0::api::Apache::URI/C_unescape_url_>>.
+C<L<Apache2::URI::unescape_url()|docs::2.0::api::Apache2::URI/C_unescape_url_>>.
@@ -1665,7 +1627,7 @@
(http://search.cpan.org/dist/HTML-Parser/lib/HTML/Entities.pm).
It's also available via
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> for backwards
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> for backwards
compatibility.
@@ -1682,29 +1644,29 @@
=head2 C<Apache::Util::ht_time()>
-C<L<Apache::Util::ht_time()|docs::2.0::api::Apache::Util/C_ht_time_>>
+C<L<Apache2::Util::ht_time()|docs::2.0::api::Apache2::Util/C_ht_time_>>
now requires a C<L<pool|docs::2.0::api::APR::Pool>> object as a first
argument.
For example:
- use Apache::Util ();
+ use Apache2::Util ();
$fmt = '%a, %d %b %Y %H:%M:%S %Z';
$gmt = 1;
- $fmt_time = Apache::Util::ht_time($r->pool, time(), $fmt, $gmt);
+ $fmt_time = Apache2::Util::ht_time($r->pool, time(), $fmt, $gmt);
-See the L<Apache::Util|docs::2.0::api::Apache::Util> manpage.
+See the L<Apache2::Util|docs::2.0::api::Apache2::Util> manpage.
It's also possible to adjust the mod_perl 1.0 code using
-Apache::compat's
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
+Apache2::compat's
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
For example:
- use Apache::compat;
- Apache::compat::override_mp2_api('Apache::Util::ht_time');
- $fmt_time = Apache::Util::ht_time(time(), $fmt, $gmt);
- Apache::compat::restore_mp2_api('Apache::Util::ht_time');
+ use Apache2::compat;
+ Apache2::compat::override_mp2_api('Apache2::Util::ht_time');
+ $fmt_time = Apache2::Util::ht_time(time(), $fmt, $gmt);
+ Apache2::compat::restore_mp2_api('Apache2::Util::ht_time');
@@ -1717,7 +1679,7 @@
C<L<APR::Util::password_validate()|docs::2.0::api::APR::Util/C_password_validate_>>. For
example:
- my $ok = Apache::Util::password_validate("stas", "ZeO.RAc3iYvpA");
+ my $ok = Apache2::Util::password_validate("stas", "ZeO.RAc3iYvpA");
@@ -1778,19 +1740,19 @@
information.
It's also possible to adjust the behavior to be mod_perl 1.0
-compatible using Apache::compat's
-L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>,
+compatible using Apache2::compat's
+L<overriding|docs::2.0::api::Apache2::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>,
in which case C<unparse()> will transparently set I<scheme> to
I<http>.
# request http://localhost.localdomain:8529/TestAPI::uri
- Apache::compat::override_mp2_api('APR::URI::unparse');
+ Apache2::compat::override_mp2_api('APR::URI::unparse');
my $parsed = $r->parsed_uri;
# set hostname, but not the scheme
$parsed->hostname($r->get_server_name);
$parsed->port($r->get_server_port);
print $parsed->unparse;
- Apache::compat::restore_mp2_api('APR::URI::unparse');
+ Apache2::compat::restore_mp2_api('APR::URI::unparse');
prints:
@@ -1886,7 +1848,6 @@
Here is how to write a simple I<Makefile.PL> for modules wanting to
build XS code against mod_perl 2.0:
- use Apache2;
use mod_perl 1.99;
use ModPerl::MM ();
@@ -1915,7 +1876,7 @@
=head1 C<Apache::SIG>
C<Apache::SIG> currently exists only
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> and it does
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> and it does
nothing.
@@ -1925,17 +1886,17 @@
=head1 C<Apache::StatINC>
C<Apache::StatINC> has been replaced by
-C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>, which works for
-both mod_perl generations. To migrate to C<Apache::Reload> simply
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>>, which works for
+both mod_perl generations. To migrate to C<Apache2::Reload> simply
replace:
PerlInitHandler Apache::StatINC
with:
- PerlInitHandler Apache::Reload
+ PerlInitHandler Apache2::Reload
-However C<Apache::Reload> provides an extra functionality, covered in
+However C<Apache2::Reload> provides an extra functionality, covered in
the module's manpage.
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod?view=diff&r1=159854&r2=159855
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod Sat Apr 2 17:04:11 2005
@@ -49,7 +49,7 @@
=back
B<Do not be alarmed!> One way to deal with all of these issues is to
-load the C<L<Apache::compat|docs::2.0::api::Apache::compat>>
+load the C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>
compatibility layer bundled with mod_perl 2.0. This magic spell will
make almost any 1.0 module run under 2.0 without further changes. It
is by no means the solution for every case, however, so please read
@@ -60,18 +60,18 @@
=over
-=item 1 Run the module on 2.0 under C<Apache::compat> with no further changes
+=item 1 Run the module on 2.0 under C<Apache2::compat> with no further changes
As we have said mod_perl 2.0 ships with a module,
-C<L<Apache::compat|docs::2.0::api::Apache::compat>>, that provides a
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>>, that provides a
complete drop-in compatibility layer for 1.0
-modules. C<Apache::compat> does the following:
+modules. C<Apache2::compat> does the following:
=over
=item *
-Loads all the mod_perl 2.0 Apache:: modules
+Loads all the mod_perl 2.0 Apache2:: modules
=item *
@@ -83,11 +83,11 @@
=back
-The drawback to using C<Apache::compat> is the performance hit, which
+The drawback to using C<Apache2::compat> is the performance hit, which
can be significant.
Authors of CPAN and other publicly distributed modules should not use
-C<Apache::compat> since this forces its use in environments where the
+C<Apache2::compat> since this forces its use in environments where the
administrator may have chosen to optimize memory use by making all
code run natively under 2.0.
@@ -119,34 +119,32 @@
The following sections provide more detailed information and
instructions for each of these three porting strategies.
-=head1 Using C<Apache::porting>
+=head1 Using C<Apache2::porting>
META: to be written. this is a new package which makes chunks of this
doc simpler. for now see the
-C<L<Apache::porting|docs::2.0::api::Apache::porting>> manpage.
+C<L<Apache2::porting|docs::2.0::api::Apache2::porting>> manpage.
-=head1 Using the C<Apache::compat> Layer
+=head1 Using the C<Apache2::compat> Layer
-The C<L<Apache::compat|docs::2.0::api::Apache::compat>> module tries
+The C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> module tries
to hide the changes in API prototypes between version 1.0 and 2.0 of
mod_perl, and implements "virtual methods" for the methods and
functions that actually no longer exist.
-C<Apache::compat> is extremely easy to use. Either add at the very
+C<Apache2::compat> is extremely easy to use. Either add at the very
beginning of startup.pl:
- use Apache2;
- use Apache::compat;
+ use Apache2::compat;
or add to httpd.conf:
- PerlModule Apache2
- PerlModule Apache::compat
+ PerlModule Apache2::compat
That's all there is to it. Now you can run your 1.0 module unchanged.
-Remember, however, that using C<Apache::compat> will make your module
+Remember, however, that using C<Apache2::compat> will make your module
run slower. It can create a larger memory footprint than you need and
it implements functionality in pure Perl that is provided in much
faster XS in mod_perl 1.0 as well as in 2.0. This module was really
@@ -155,7 +153,7 @@
It's also especially important to repeat that C<L<CPAN module
developers are requested not to use this module in their
-code|docs::2.0::api::Apache::compat/Use_in_CPAN_Modules>>, since this
+code|docs::2.0::api::Apache2::compat/Use_in_CPAN_Modules>>, since this
takes the control over performance away from users.
=head1 Porting a Perl Module to Run under mod_perl 2.0
@@ -194,16 +192,16 @@
to figure out which module provides this method. We can just run this
from the command line:
- % perl -MApache2 -MModPerl::MethodLookup -e print_method content_type
+ % perl -MModPerl::MethodLookup -e print_method content_type
This prints:
to use method 'content_type' add:
- use Apache::RequestRec ();
+ use Apache2::RequestRec ();
We do what it says and add this C<use()> statement to our code,
restart our server (unless we're using
-C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>), and mod_perl
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>>), and mod_perl
will no longer complain about this particular method.
Since you may need to use this technique quite often you may want to
@@ -231,12 +229,12 @@
There is more than one class with method 'print'
try one of:
- use Apache::RequestIO ();
- use Apache::Filter ();
+ use Apache2::RequestIO ();
+ use Apache2::Filter ();
So there is more than one package that has this method. Since we know
that we call the C<print()> method with the C<$r> object, it must be
-the C<Apache::RequestIO> module that we are after. Indeed, loading
+the C<Apache2::RequestIO> module that we are after. Indeed, loading
this module solves the problem.
=head3 Using C<ModPerl::MethodLookup> Programmatically
@@ -246,9 +244,9 @@
C<L<lookup_method|docs::2.0::api::ModPerl::MethodLookup/lookup_method__>>
accepts an object as an optional second argument, which is used if
there is more than one module that contains the method in
-question. C<ModPerl::MethodLookup> knows that C<Apache::RequestIO> and
-and C<Apache::Filter> expect an object of type C<Apache::RequestRec>
-and type C<Apache::Filter> respectively. So in a program running under
+question. C<ModPerl::MethodLookup> knows that C<Apache2::RequestIO> and
+and C<Apache2::Filter> expect an object of type C<Apache2::RequestRec>
+and type C<Apache2::Filter> respectively. So in a program running under
mod_perl we can call:
ModPerl::MethodLookup::lookup_method('print', $r);
@@ -314,7 +312,7 @@
call to C<log_reason()>. But when we use C<ModPerl::MethodLookup> to see
which module to load in order to call that method, nothing is found:
- % perl -MApache2 -MModPerl::MethodLookup -le \
+ % perl -MModPerl::MethodLookup -le \
'print((ModPerl::MethodLookup::lookup_method(shift))[0])' \
log_reason
@@ -328,7 +326,7 @@
suspected, the method C<log_reason()> no longer exists, and that
L<instead we should use the other standard logging
functions|docs::2.0::user::porting::compat/C__r_E_gt_log_reason_>
-provided by the C<Apache::Log> module.
+provided by the C<Apache2::Log> module.
=head3 Methods Whose Usage Has Been Modified
@@ -338,10 +336,10 @@
For example, say our mod_perl 1.0 code said:
- $parsed_uri = Apache::URI->parse($r, $r->uri);
+ $parsed_uri = Apache2::URI->parse($r, $r->uri);
This code causes mod_perl 2.0 to complain first about not being able
-to load the method C<parse()> via the package Apache::URI. We use the
+to load the method C<parse()> via the package Apache2::URI. We use the
tools described above to discover that the package containing our
method has moved and change our code to load and use C<APR::URI>:
@@ -365,12 +363,10 @@
To require a module to run only under 2.0, simply add:
- use Apache2;
use mod_perl 2.0;
META: In fact, before 2.0 is released you really have to say:
- use Apache2;
use mod_perl 1.99;
And you can even require a specific version (for example when a
@@ -387,50 +383,18 @@
new version, it's best to try to preserve the name and use some
workarounds.
-Let's say that you have a module C<Apache::Friendly> whose release
-version compliant with mod_perl 1.0 is 1.57. You keep this version on
-CPAN and release a new version, 2.01, which is compliant with mod_perl
-2.0 and preserves the name of the module. It's possible that a user
-may need to have both versions of the module on the same
-machine. Since the two have the same name they obviously cannot live
-under the same tree.
+META: need to discuss this more.
-One attempt to solve this problem is to use I<Makefile.PL>'s
-C<MP_INST_APACHE2> option. If the module is configured as:
-
- % perl Makefile.PL MP_INST_APACHE2=1
-
-it'll be installed relative to the I<Apache2/> directory.
-
-META: but of course this won't work in non-core mod_perl, since a
-generic C<Makefile.PL> has no idea what to do about
-C<MP_INST_APACHE2=1>. Need to provide copy-n-paste recipe for this. Or
-even add to the core a supporting module that will handle this
-functionality.
-
-The second step is to change the documentation of your 2.0 compliant
-module to instruct users to C<use Apache2 ();> in their code (or in
-I<startup.pl> or via C<PerlModule Apache2> in I<httpd.conf>) before
-the module is required. This will cause C<@INC> to be modified to
-include the I<Apache2/> directory first.
-
-The introduction of the I<Apache2/> directory is similar to how Perl
-installs its modules in a version specific directory. For example:
-
- lib/5.7.1
- lib/5.7.2
-
-
-=head2 Using C<Apache::compat> As a Tutorial
+=head2 Using C<Apache2::compat> As a Tutorial
Even if you have followed the recommendation and eschewed use of the
-C<L<Apache::compat|docs::2.0::api::Apache::compat>> module, you may
+C<L<Apache2::compat|docs::2.0::api::Apache2::compat>> module, you may
find it useful to learn how the API has been changed and how to modify
-your own code. Simply look at the C<Apache::compat> source code and see
+your own code. Simply look at the C<Apache2::compat> source code and see
how the functionality should be implemented in mod_perl 2.0.
For example, mod_perl 2.0 doesn't provide the C<Apache-E<gt>gensym>
-method. As we can see if we look at the C<Apache/compat.pm> source,
+method. As we can see if we look at the C<Apache2/compat.pm> source,
the functionality is now available via the core Perl module C<Symbol>
and its C<gensym()> function. (Since mod_perl 2.0 works only with Perl
versions 5.6 and higher, and C<Symbol.pm> is included in the core Perl
@@ -495,24 +459,24 @@
=head4 I<httpd.conf>
-Next, I configure the C<Apache::Reload> module, so we don't have to
+Next, I configure the C<Apache2::Reload> module, so we don't have to
constantly restart the server after we modify C<Apache::MP3>. In order
to do that add to I<httpd.conf>:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
- PerlSetVar ReloadModules "ModPerl::* Apache::*"
+ PerlSetVar ReloadModules "ModPerl::* Apache2::*"
PerlSetVar ReloadConstantRedefineWarnings Off
-You can refer to C<L<the Apache::Reload
-manpage|docs::2.0::api::Apache::Reload>> for more information if
+You can refer to C<L<the Apache2::Reload
+manpage|docs::2.0::api::Apache2::Reload>> for more information if
you aren't familiar with this module. The part:
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules "ModPerl::* Apache::*"
-tells C<Apache::Reload> to monitor only modules in the C<ModPerl::>
+tells C<Apache2::Reload> to monitor only modules in the C<ModPerl::>
and C<Apache::> namespaces. So C<Apache::MP3> will be monitored. If
your module is named C<Foo::Bar>, make sure to include the right
pattern for the C<ReloadModules> directive. Alternatively simply have:
@@ -531,7 +495,7 @@
If you do change those constants, refer to the section on
C<L<ReloadConstantRedefineWarnings
-|docs::2.0::api::Apache::Reload/Silencing__Constant_subroutine_____redefined_at__Warnings>>.
+|docs::2.0::api::Apache2::Reload/Silencing__Constant_subroutine_____redefined_at__Warnings>>.
Next I configured C<Apache::MP3>. In my case I've followed the
C<Apache::MP3> documentation, created a directory I<mp3/> under the
@@ -551,8 +515,8 @@
PerlRequire "/home/httpd/2.0/perl/startup.pl"
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules "ModPerl::* Apache::*"
PerlSetVar ReloadConstantRedefineWarnings Off
@@ -574,13 +538,12 @@
Since chances are that no mod_perl 1.0 module will work out of box
without at least preloading some modules, I've enabled the
-C<Apache::compat> module. Now my I<startup.pl> looked like this:
+C<Apache2::compat> module. Now my I<startup.pl> looked like this:
#file:startup.pl
#---------------
- use Apache2 ();
use lib qw(/home/httpd/2.0/perl);
- use Apache::compat;
+ use Apache2::compat;
=head4 I<Apache/MP3.pm>
@@ -650,7 +613,7 @@
(I also have a similar set of aliases for mod_perl 1.0)
-=head3 Porting with C<Apache::compat>
+=head3 Porting with C<Apache2::compat>
I have configured my server to listen on port 8002, so I issue a
request http://localhost:8002/mp3/ in one console:
@@ -668,7 +631,7 @@
When the request is issued, the I<error_log> file tells me:
[Thu Jun 05 15:29:45 2003] [error] [client 127.0.0.1]
- Usage: Apache::RequestRec::new(classname, c, base_pool=NULL)
+ Usage: Apache2::RequestRec::new(classname, c, base_pool=NULL)
at .../Apache/MP3.pm line 60.
Looking at the code:
@@ -679,7 +642,7 @@
The problem is that handler wasn't invoked as method, but had C<$r>
passed to it (we can tell because C<new()> was invoked as
-C<Apache::RequestRec::new()>, whereas it should have been
+C<Apache2::RequestRec::new()>, whereas it should have been
C<Apache::MP3::new()>. Why I<Apache::MP3> wasn't passed as the first
argument? I go to L<the mod_perl 1.0 backward compatibility
document|docs::2.0::user::porting::compat/> and find that
@@ -839,24 +802,23 @@
some usage patterns which may be still problematic. But this is good
enough for this tutorial.
-=head3 Getting Rid of the C<Apache::compat> Dependency
+=head3 Getting Rid of the C<Apache2::compat> Dependency
-The final stage is going to get rid of C<Apache::compat> since this is
-a CPAN module, which must not load C<Apache::compat> on its own. I'm
+The final stage is going to get rid of C<Apache2::compat> since this is
+a CPAN module, which must not load C<Apache2::compat> on its own. I'm
going to make C<Apache::MP3> work with mod_perl 2.0 all by itself.
-The first step is to comment out the loading of C<Apache::compat> in
+The first step is to comment out the loading of C<Apache2::compat> in
I<startup.pl>:
#file:startup.pl
#---------------
- use Apache2 ();
use lib qw(/home/httpd/2.0/perl);
- #use Apache::compat ();
+ #use Apache2::compat ();
-=head3 Ensuring that C<Apache::compat> is not loaded
+=head3 Ensuring that C<Apache2::compat> is not loaded
-The second step is to make sure that C<Apache::compat> doesn't get
+The second step is to make sure that C<Apache2::compat> doesn't get
loaded indirectly, through some other module. So I've added this line
of code to I<Apache/MP3.pm>:
@@ -865,17 +827,17 @@
@@ -3,2 +3,6 @@
+BEGIN {
- + die "Apache::compat is loaded loaded" if $INC{'Apache/compat.pm'};
+ + die "Apache2::compat is loaded loaded" if $INC{'Apache2/compat.pm'};
+}
+
use strict;
and indeed, even though I've commented out the loading of
-C<Apache::compat> from I<startup.pl>, this module was still getting
+C<Apache2::compat> from I<startup.pl>, this module was still getting
loaded. I knew that because the request to I</mp3> were failing with
the error message:
- Apache::compat is loaded loaded at ...
+ Apache2::compat is loaded loaded at ...
There are several ways to find the guilty party, you can C<grep(1)>
for it in the perl libraries, you can override
@@ -884,30 +846,30 @@
BEGIN {
use Carp;
*CORE::GLOBAL::require = sub {
- Carp::cluck("Apache::compat is loaded") if $_[0] =~ /compat/;
+ Carp::cluck("Apache2::compat is loaded") if $_[0] =~ /compat/;
CORE::require(@_);
};
}
-or you can modify I<Apache/compat.pm> and make it print the calls
+or you can modify I<Apache2/compat.pm> and make it print the calls
trace when it gets compiled:
- --- Apache/compat.pm.orig 2003-06-03 16:11:07.000000000 +1000
- +++ Apache/compat.pm 2003-06-03 16:11:58.000000000 +1000
+ --- Apache2/compat.pm.orig 2003-06-03 16:11:07.000000000 +1000
+ +++ Apache2/compat.pm 2003-06-03 16:11:58.000000000 +1000
@@ -1,5 +1,9 @@
- package Apache::compat;
+ package Apache2::compat;
+BEGIN {
+ use Carp;
- + Carp::cluck("Apache::compat is loaded by");
+ + Carp::cluck("Apache2::compat is loaded by");
+}
I've used this last technique, since it's the safest one to use.
-Remember that C<Apache::compat> can also be loaded with:
+Remember that C<Apache2::compat> can also be loaded with:
- do "Apache/compat.pm";
+ do "Apache2/compat.pm";
-in which case, neither C<grep(1)>'ping for C<Apache::compat>, nor
+in which case, neither C<grep(1)>'ping for C<Apache2::compat>, nor
overriding C<require()> will do the job.
When I've restarted the server and tried to use C<Apache::MP3> (I
@@ -915,31 +877,31 @@
to start normally and cope with problem when it's running), the
I<error_log> had an entry:
- Apache::compat is loaded by at .../Apache2/Apache/compat.pm line 6
- Apache::compat::BEGIN() called at .../Apache2/Apache/compat.pm line 8
- eval {...} called at .../Apache2/Apache/compat.pm line 8
- require Apache/compat.pm called at .../5.9.0/CGI.pm line 169
+ Apache2::compat is loaded by at .../Apache2/compat.pm line 6
+ Apache2::compat::BEGIN() called at .../Apache2/compat.pm line 8
+ eval {...} called at .../Apache2/compat.pm line 8
+ require Apache2/compat.pm called at .../5.9.0/CGI.pm line 169
require CGI.pm called at .../site_perl/5.9.0/Apache/MP3.pm line 8
- Apache::MP3::BEGIN() called at .../Apache2/Apache/compat.pm line 8
+ Apache::MP3::BEGIN() called at .../Apache2/compat.pm line 8
(I've trimmed the whole paths of the libraries and the trace itself,
to make it easier to understand.)
We could have used C<Carp::carp()> which would have told us only the
-fact that C<Apache::compat> was loaded by C<CGI.pm>, but by using
+fact that C<Apache2::compat> was loaded by C<CGI.pm>, but by using
C<Carp::cluck()> we've obtained the whole stack backtrace so we also
can learn which module has loaded C<CGI.pm>.
Here I've learned that I had an old version of C<CGI.pm> (2.89) which
-automatically loaded C<Apache::compat> (which L<should be never done
+automatically loaded C<Apache2::compat> (which L<should be never done
by CPAN
-modules|docs::2.0::api::Apache::compat/Use_in_CPAN_Modules>). Once
+modules|docs::2.0::api::Apache2::compat/Use_in_CPAN_Modules>). Once
I've upgraded C<CGI.pm> to version 2.93 and restarted the server,
-C<Apache::compat> wasn't getting loaded any longer.
+C<Apache2::compat> wasn't getting loaded any longer.
=head3 Installing the C<ModPerl::MethodLookup> Helper
-Now that C<Apache::compat> is not loaded, I need to deal with two
+Now that C<Apache2::compat> is not loaded, I need to deal with two
issues: modules that need to be loaded and APIs that have changed.
For the second issue I'll have to refer to the L<the mod_perl 1.0
@@ -958,7 +920,6 @@
#file:startup.pl
#---------------
- use Apache2 ();
use lib qw(/home/httpd/2.0/perl);
{
@@ -968,7 +929,7 @@
use Carp;
sub handler {
- # look inside mod_perl:: Apache:: APR:: ModPerl:: excluding DESTROY
+ # look inside mod_perl:: Apache2:: APR:: ModPerl:: excluding DESTROY
my $skip = '^(?!DESTROY$';
*UNIVERSAL::AUTOLOAD = sub {
my $method = $AUTOLOAD;
@@ -1018,7 +979,7 @@
no warnings 'redefine'; # XXX: remove when done with porting
-use Apache::Constants qw(:common REDIRECT HTTP_NO_CONTENT DIR_MAGIC_TYPE HTTP_NOT_MODIFIED);
- +use Apache::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
+ +use Apache2::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
+ DIR_MAGIC_TYPE HTTP_NOT_MODIFIED);
+
use Apache::MP3::L10N;
@@ -1026,10 +987,10 @@
use Socket 'sockaddr_in';
and I also had to adjust the constants, since what used to be C<OK>,
-now has to be C<Apache::OK>, mainly because in mod_perl 2.0 there is
+now has to be C<Apache2::OK>, mainly because in mod_perl 2.0 there is
an enormous amount of constants (coming from Apache and APR) and most
-of them are grouped in C<Apache::> or C<APR::> namespaces. The
-C<L<Apache::Const|docs::2.0::api::Apache::Const>> and
+of them are grouped in C<Apache2::> or C<APR::> namespaces. The
+C<L<Apache2::Const|docs::2.0::api::Apache2::Const>> and
C<L<APR::Const|docs::2.0::api::APR::Const>> manpage provide more
information on available constants.
@@ -1037,7 +998,7 @@
% perl -pi -e 's/return\s(OK|DECLINED|FORBIDDEN| \
REDIRECT|HTTP_NO_CONTENT|DIR_MAGIC_TYPE| \
- HTTP_NOT_MODIFIED)/return Apache::$1/xg' Apache/MP3.pm
+ HTTP_NOT_MODIFIED)/return Apache2::$1/xg' Apache/MP3.pm
As you can see the regex explicitly lists all constants that were used
in C<Apache::MP3>. Your situation may vary. Here is the patch:
@@ -1053,7 +1014,7 @@
my $mime = $self->r->lookup_file("$dir/$d")->content_type;
- push(@directories,$d) if !$seen{$d}++ && $mime eq DIR_MAGIC_TYPE;
- + push(@directories,$d) if !$seen{$d}++ && $mime eq Apache::DIR_MAGIC_TYPE;
+ + push(@directories,$d) if !$seen{$d}++ && $mime eq Apache2::DIR_MAGIC_TYPE;
# .m3u files should be configured as audio/playlist MIME types in your apache .conf file
push(@playlists,$d) if $mime =~ m!^audio/(playlist|x-mpegurl|mpegurl|x-scpls)$!;
@@ -1062,7 +1023,7 @@
[Fri Jun 06 17:28:00 2003] [error] [client 127.0.0.1]
Can't locate object method "header_in" via package
- "Apache::RequestRec" at .../Apache/MP3.pm line 85.
+ "Apache2::RequestRec" at .../Apache2/MP3.pm line 85.
The L<porting document|docs::2.0::user::porting::compat> quickly
L<reveals|docs::2.0::user::porting::compat/C__r_E_gt_err_header_out_>
@@ -1103,7 +1064,7 @@
+use APR::Table ();
+
- use Apache::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
+ use Apache2::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
DIR_MAGIC_TYPE HTTP_NOT_MODIFIED);
I continue issuing the request and adding the missing modules again
@@ -1116,17 +1077,17 @@
use warnings;
no warnings 'redefine'; # XXX: remove when done with porting
- +use Apache::Connection ();
- +use Apache::SubRequest ();
- +use Apache::Access ();
- +use Apache::RequestIO ();
- +use Apache::RequestUtil ();
- +use Apache::RequestRec ();
- +use Apache::ServerUtil ();
- +use Apache::Log;
+ +use Apache2::Connection ();
+ +use Apache2::SubRequest ();
+ +use Apache2::Access ();
+ +use Apache2::RequestIO ();
+ +use Apache2::RequestUtil ();
+ +use Apache2::RequestRec ();
+ +use Apache2::ServerUtil ();
+ +use Apache2::Log;
use APR::Table ();
- use Apache::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
+ use Apache2::Const -compile => qw(:common REDIRECT HTTP_NO_CONTENT
The AUTOLOAD code helped me to trace the modules that contain the
existing APIs, however I still have to deal with APIs that no longer
@@ -1151,7 +1112,7 @@
- $self->r->send_http_header( $self->html_content_type );
+ $self->r->content_type( $self->html_content_type );
- return Apache::OK if $self->r->header_only;
+ return Apache2::OK if $self->r->header_only;
print start_html(
@@ -336,7 +336,7 @@
@@ -1160,22 +1121,22 @@
- $r->send_http_header('audio/mpegurl');
+ $r->content_type('audio/mpegurl');
- return Apache::OK if $r->header_only;
+ return Apache2::OK if $r->header_only;
# local user
@@ -495,7 +495,7 @@
- return Apache::DECLINED unless my ($directories,$mp3s,$playlists,$txtfiles)
+ return Apache2::DECLINED unless my ($directories,$mp3s,$playlists,$txtfiles)
= $self->read_directory($dir);
- $self->r->send_http_header( $self->html_content_type );
+ $self->r->content_type( $self->html_content_type );
- return Apache::OK if $self->r->header_only;
+ return Apache2::OK if $self->r->header_only;
$self->page_top($dir);
also I've noticed that there was this code:
- return Apache::OK if $self->r->header_only;
+ return Apache2::OK if $self->r->header_only;
This technique is no longer needed in 2.0, since Apache 2.0
automatically discards the body if the request is of type C<HEAD> --
@@ -1185,7 +1146,7 @@
requests.
At this point I was able to browse the directories and play files via
-most options without relying on C<Apache::compat>.
+most options without relying on C<Apache2::compat>.
There were a few other APIs that I had to fix in the same way, while
trying to use the application, looking at the I<error_log> referring
@@ -1202,7 +1163,7 @@
=item C<send_fd()>
As of this writing we don't have this function in the core, because
-Apache 2.0 doesn't have it (it's in C<Apache::compat> but implemented
+Apache 2.0 doesn't have it (it's in C<Apache2::compat> but implemented
in a slow way). However we may provide one in the future. Currently
one can use the function C<sendfile()> which requires a filename as an
argument and not the file descriptor. So I have fixed the code:
@@ -1213,7 +1174,7 @@
- close(FILE);
+
+ if($r->content_type eq 'audio/x-scpls'){
- + $r->sendfile($r->filename) || return Apache::NOT_FOUND;
+ + $r->sendfile($r->filename) || return Apache2::NOT_FOUND;
=item C<log_reason>
@@ -1297,14 +1258,14 @@
</IfDefine>
From within Perl code this can be tested with
-C<Apache::exists_config_define()>. For example, we can use this method
+C<Apache2::exists_config_define()>. For example, we can use this method
to decide whether or not to call C<$r-E<gt>send_http_header()>, which
no longer exists in mod_perl 2.0:
sub handler {
my $r = shift;
$r->content_type('text/html');
- $r->send_http_header() unless Apache::exists_config_define("MODPERL2");
+ $r->send_http_header() unless Apache2::exists_config_define("MODPERL2");
...
}
@@ -1335,26 +1296,26 @@
such code.
Here are two complete examples. The first example implements
-C<MyApache::Method> which has a single method that works for both
+C<MyApache2::Method> which has a single method that works for both
mod_perl generations:
The configuration:
- PerlModule MyApache::Method
+ PerlModule MyApache2::Method
<Location /method>
SetHandler perl-script
- PerlHandler MyApache::Method->handler
+ PerlHandler MyApache2::Method->handler
</Location>
The code:
- #file:MyApache/Method.pm
- package MyApache::Method;
+ #file:MyApache2/Method.pm
+ package MyApache2::Method;
- # PerlModule MyApache::Method
+ # PerlModule MyApache2::Method
# <Location /method>
# SetHandler perl-script
- # PerlHandler MyApache::Method->handler
+ # PerlHandler MyApache2::Method->handler
# </Location>
use strict;
@@ -1365,10 +1326,10 @@
BEGIN {
if (MP2) {
- require Apache::RequestRec;
- require Apache::RequestIO;
- require Apache::Const;
- Apache::Const->import(-compile => 'OK');
+ require Apache2::RequestRec;
+ require Apache2::RequestIO;
+ require Apache2::Const;
+ Apache2::Const->import(-compile => 'OK');
}
else {
require Apache;
@@ -1386,30 +1347,30 @@
MP2 ? $r->content_type('text/plain')
: $r->send_http_header('text/plain');
print "$class was called\n";
- return MP2 ? Apache::OK : Apache::Constants::OK;
+ return MP2 ? Apache2::OK : Apache::Constants::OK;
}
Here are two complete examples. The second example implements
-C<MyApache::Method2>, which is very similar to C<MyApache::Method>,
+C<MyApache2::Method2>, which is very similar to C<MyApache2::Method>,
but uses separate methods for mod_perl 1.0 and 2.0 servers.
The configuration is the same:
- PerlModule MyApache::Method2
+ PerlModule MyApache2::Method2
<Location /method2>
SetHandler perl-script
- PerlHandler MyApache::Method2->handler
+ PerlHandler MyApache2::Method2->handler
</Location>
The code:
- #file:MyApache/Method2.pm
- package MyApache::Method2;
+ #file:MyApache2/Method2.pm
+ package MyApache2::Method2;
- # PerlModule MyApache::Method
+ # PerlModule MyApache2::Method
# <Location /method>
# SetHandler perl-script
- # PerlHandler MyApache::Method->handler
+ # PerlHandler MyApache2::Method->handler
# </Location>
use strict;
@@ -1421,10 +1382,10 @@
BEGIN {
warn "running $mod_perl::VERSION!\n";
if (MP2) {
- require Apache::RequestRec;
- require Apache::RequestIO;
- require Apache::Const;
- Apache::Const->import(-compile => 'OK');
+ require Apache2::RequestRec;
+ require Apache2::RequestIO;
+ require Apache2::Const;
+ Apache2::Const->import(-compile => 'OK');
}
else {
require Apache;
@@ -1449,351 +1410,30 @@
my($class, $r) = @_;
$r->content_type('text/plain');
$r->print("mp2: $class was called\n");
- return Apache::OK();
+ return Apache2::OK();
}
Assuming that mod_perl 1.0 is listening on port 8001 and mod_perl 2.0
on 8002, we get the following results:
% lynx --source http://localhost:8001/method
- MyApache::Method was called
+ MyApache2::Method was called
% lynx --source http://localhost:8001/method2
- mp1: MyApache::Method2 was called
+ mp1: MyApache2::Method2 was called
% lynx --source http://localhost:8002/method
- MyApache::Method was called
+ MyApache2::Method was called
% lynx --source http://localhost:8002/method2
- mp2: MyApache::Method2 was called
+ mp2: MyApache2::Method2 was called
=head1 The Conflict of mp1 vs mp2 vs mp22 vs ... vs mpNN
-The following sections summarise issues involving co-existence of
-several mod_perl generations on CPAN and user's filesystem.
-
-
-=head2 Why mod_perl2 didn't Rename its API
-
-The reason for not renaming mp2 core and 3rd party modules APIs to
-embed the version number like (mod_perl2, Apache2::Cookie,
-Apache2::Scoreboard, Apache2::SizeLimit, etc.) is very simple and
-logical. Even though the internals of mp2 core and 3rd party modules
-are totally different from their mp1 counterparts, for the most parts
-the user API hasn't changed at all. Renaming the API is
-counterproductive, as it'll will impose extra work on the modperl
-users, and dangerous as the added complication may drive the users
-away to use other similar technologies which don't have this kludge.
-
-Add to the fact that one Apache-2.2 is released, if mp2 doesn't manage
-to make the incompatible changes in Apache 2.2 transparent to modperl
-users, there will be mp2.2, and we would have needed to make yet
-another namespace rename, even though 99% of the API will be the same
-as mp2.0. Then there will be mp2.4, mp2.6, mp2.8, mp3.0, etc. I hope
-you get the idea.
-
-mp2 provides a Perl API for libapr and libaprutil projects (which can
-be used even if you don't run modperl). At the moment there is libapr
-0.9.x, 1.x and 2.x will be released soon. All those are partially
-incompatible. Since modperl provides only a partial mapping to the C
-APR API the mod_perl users so far can run their code unmodified no
-matter whether they have libapr-0.9, libapr-1.0 or libapr-2.0
-installed. If we were to embed the numbers in the API, users would
-have had to rewrite their application to make it support each new
-release of APR.
-
-Let's look at the multiple C libraries you have installed on your
-machine. 99% of the libraries do not change their API naming when they
-release a new version. Take for example the Berkley DB library. It had
-dbopen(3) for its 1st generation, and 2nd, and 3rd, and 4th.
-
-I hope you now understand why the API should not include a generation
-number in it.
-
-=over
-
-=item Q. Why not use some smart namespace aliasing? e.g. to alias
-C<Apache2::SizeLimit> to C<Apache::SizeLimit> at run time, so the old
-application will work just as well.
-
-A. That would be a workable solution, if the Apache C API didn't have
-methods, which have exactly the same name and arguments in 1.3 and
-2.0, but which do totally different things. One example is
-C<L<Apache::Connection::local_addr|docs::2.0::user::porting::compat/C__connection_E_gt_remote_addr_>>,
-which in mp1 returned a C Socket object which was decoded by
-C<Socket::sockaddr_in>, whereas in mp2 it returns an
-C<APR::SockAddr> object.
-
-
-=back
-
-
-
-
-
-=head2 Platform Support for Multiple Generations of the Same Project
-
-The next issue to look at is the platform/language support for
-multiple generations of the same project.
-
-99% of users will have only one mod_perl installed under the same perl
-tree. So for most users the following issues are non-existent. For
-those few users that need to have more than one mod_perl installed
-under the same tree, the problems and their solutions are discussed
-next.
-
-=head3 (.pm|.so) Files Collision
-
-Again, let's start with the C libraries, and again use Berkley DB
-example.
-
-The public C API lives in its header files. Those headers files don't
-change much between generations, some APIs are modified, others remain
-as before. The header files usually keep the same names. So how can
-you have Berkley DB 1 and 4 on the same machine, while most of the
-header files have the same names? This is done by installing each
-generation into a different sub-directory. On my machine I have db1
-and db4, let's look at F<db.h> header file:
-
- /usr/include/db1/db.h
- /usr/include/db4/db.h
-
-Notice that it's the same name, and there is no problem. When an
-application wants to use either of the two the user tells it which of
-the include directories to use at compile time.
-
-The binary of the C library is usually just one file (.so or .a on
-unices), so on my machine I have:
-
- /usr/lib/libdb1.so
- /usr/lib/libdb-4.so
-
-let's ignore the fact that those are symlinks for the purpose of this
-discussion. Again the application at compile time is told which of the
-two libraries it should use at loading time.
-
-Now, let's go back to Perl. Perl doesn't provide any support for
-multiple generations of the same project. There are a few workarounds:
-
-=over
-
-=item 1
-
-install a different perl for each separate version of project, in
-which case there is no problem with co-existence.
-
-=item 2
-
-install the second generation in some other directory and adjust
-C<@INC> at perl startup, so that this new directory will appear first.
-
-C<only> and C<only::install> (http://search.cpan.org/dist/only/) do
-exactly that.
-
-=back
-
-mp2 users have to use one of these workarounds. In the case of the
-second workaround, mod_perl uses its own implementation, called
-F<Apache2.pm>. In order to make mp2 co-exist with mp1 install, one
-needs to install mp2 modules in a sub-directory C<Apache2/>. The
-modperl core installer will make sure that this happens if it detects
-that mp1 was installed. 3rd party modules writers need to use
-C<L<ModPerl::MM::WriteMakefile|docs::2.0::api::ModPerl::MM>> which
-will do the right thing. At run time loading F<Apache.pm> will
-L<adjust
-@INC|docs::2.0::user::config::config/Accessing_the_mod_perl_2_0_Modules>
-to include the right paths.
-
-F<Apache2.pm> which is better than C<only::install> because if you
-don't have mp1 installed, F<Apache2.pm> becomes a no-op, as mp2 is not
-getting installed into the F<Apache2/> directory, unless you
-explicitly ask the installer to do so (by passing the
-C<MP_INST_APACHE2=1> option during C<perl Makefile.PL> phase).
-
-Serious modperl users will use the first workaround, which they were
-doing with mp1 too. Why? Because to get the best performance from
-mod_perl, you want to have a custom-compiled perl tuned for your
-needs: http://modperlbook.org/html/ch15_04.html
-
-
-=head3 Documentation and Manpages
-
-If mp2 installs its F<.pm> files under F<Apache2/> C<perldoc> won't
-find those. The alternative solution is to use C<mp2doc> provided by
-mp2, which will find the right docs.
-
-As for manpages, only one set of manpages can be installed and this
-true for any project (e.g. You can have several generations of the
-same C library installed, but you will have only one set of manpages).
-That's of course ignoring the use of the environment variable
-C<MANPATH>.
-
-So use C<mp2doc> or the online docs:
-http://perl.apache.org/docs/2.0/api/ which you can also L<build
-locally|download::docs>.
-
-
-
-
-=head3 CPAN Shells
-
-In case you have mp1 and mp2 under the same perl and mp2 is installed
-under the F<Apache2/> subdirectory, in order for CPAN shell to find
-you mp2 modules you need to invoke it as:
-
- % perl -MApache2 -MCPAN -eshell
-
-For CPANPLUS:
-
- % perl -MApache2 -MCPANPLUS -eshell
-
-If you have only mp2 and you didn't ask to install it under the
-F<Apache2/> subdirectory, no special invocation technique is required.
-
-
-
-
-
-=head2 CPAN Index
-
-Since mod_perl 2.0 was released users have noticed a problem with CPAN
-clients, which started to fetch mp2 core and 3rd party modules, in the
-case when users were still using mp1. This is not a problem of the mp2
-core or the 3rd party mod_perl modules, but a problem of PAUSE indexer
-which indexes only the latest version of each namespace, without
-supporting projects which have more than one generation, while
-preserving the same namespace, as in the case with mod_perl.
-
-This is not an issue specific to mod_perl and 3rd party Apache
-modules, it's a long existing problem with other modules such as
-C<GD>, C<SQLite>, C<Sun::Solaris::*>, etc.
-
-For example: there are two internally incompatible versions of
-C<Apache::Scoreboard> (but which otherwise work identically for
-users): http://search.cpan.org/~stas/Apache-Scoreboard-2.02/
-http://search.cpan.org/~dougm/Apache-Scoreboard-0.10/. Notice that
-each generation is developed and maintained by a different developer.
-Now C<Apache::VMonitor> which works with mp1 and mp2
-(http://search.cpan.org/dist/Apache-VMonitor/) requires a different
-generation of C<Apache::Scoreboard> depending on whether mp1 or mp2 is
-used. If the PAUSE doesn't index both generations CPAN clients cannot
-satisfy the C<Apache::VMonitor> prerequisites list. This example shows
-that this is not a problem of mp2 core, but of many other packages.
-
-The ideal solution is fix PAUSE indexer to support META.yml's
-C<generation>:
-http://module-build.sourceforge.net/META-spec-new.html#generation and
-to at least index the highest version number of each generation (or
-better index them all). That should be done using a new index file, to
-keep the older CPAN clients working correctly. Then CPAN clients
-could be adjusted to use that information to make an intelligent
-automatic and/or interactive selection of the right generation, when
-resolving dependencies or executing plain install requests.
-
-Further Ken Williams and John Peacock has suggested an alternative to
-F<META.yml> C<generation> keyword. They offer to use something like a
-"backcompat_to" field, so each distribution will be able to tell
-what's the lowest version it is backcompatible with. That will work
-too, but requires the same changes in PAUSE indexer and the CPAN
-clients.
-
-Jos I. Boumans, the main developer of CPANPLUS, suggests that the
-PAUSE indexer should index all versions of the same module on CPAN, to
-make it easier on the CPAN clients to resolve prerequisites.
-
-If the multiply version indexing is provided, to further simplify the
-work of CPAN clients I've suggested that the work of figuring out
-which mod_perl (or any other project) generation should be installed,
-by creating a convention, where a developer will upload something like
-SmartInstall::project_name (e.g.: SmartInstall::mod_perl) to CPAN, and
-the CPAN client will simply download it, when asked to install
-'project_name', that program will figure out what version is suitable
-for a user and download and install it. But that still requires to
-have multiple revisions index to be available.
-
-
-=over
-
-=item Q. Why this issue was not resolved earlier?
-
-A. The issue was raised several times on the perl5-porters and
-cpan-discuss lists over the period of the last few years. But nothing
-was implemented. You can read the details:
-
-May 2003:
-http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2003-05/msg00220.html
-
-Oct 2003:
-http://www.mail-archive.com/cpan-discuss@perl.org/msg00000.html
-Dec 2003:
-http://www.mail-archive.com/cpan-discuss@perl.org/msg00033.html
-
-Dec 2004:
-http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2004-12/msg00510.html
-http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2004-12/msg00484.html
-
-Amongst other proposed solutions, Autrijus has posted a concrete
-solution to how to fix that:
-http://www.mail-archive.com/cpan-discuss@perl.org/msg00012.html
-
-=item Q. Is it possible to find the non-indexed distros?
-
-A. The easiest way is to use http://search.cpan.org/
-
-If you use C<CPAN> shell, you can use the C<'d'> command:
-
- cpan> d /mod_perl/
- Distribution D/DO/DOUGM/mod_perl-1.27.tar.gz
- Distribution G/GO/GOZER/mod_perl-1.28.tar.gz
- Distribution G/GO/GOZER/mod_perl-1.29.tar.gz
- Distribution G/GO/GOZER/mod_perl-2.0.0-RC1.tar.gz
- Distribution G/GO/GOZER/mod_perl-2.0.0-RC2-XMas.tar.gz
-
-(META: I can't seem to find a similar functionality in CPANPLUS
-shells, if you know how please let me know.)
-
-
-=item Q. Why not Put Several Generation in the Same Distro
-
-A. 1) That doesn't fix the indexing problem.
-
-2) It introduces a huge maintenance problem
-
- cd mod_perl-1.29_01-dev
- find . | wc -l
- 285
-
- cd mod_perl-2.0.0-RC3/
- find . | wc -l
- 1022
-
-gives you an idea of how big each project is, and why it's not the
-best solution to throw things together.
-
-When mp2.2 comes out will 3 generations of the modules will be need
-into the same distro? And when mp2.4 comes out? and mp2.6? etc. You
-get the idea.
-
-3) It doesn't work if different generations are maintained by
-different authors.
-
-4) It will enforce users of both versions to upgrade when one of the
-generations makes a new release. While this may work for small
-modules, in case of mod_perl core each upgrade is not to be taken
-lightly, a lot of time, each update goes through a long acceptance
-process, so enforcing one when it's not needed is evil.
-
-It will also force including new not well tested changes in one
-generation, when the other needs to be released.
-
-=back
-
-
-
-
+META: should something be said here?
=head2 Distributors
@@ -1812,8 +1452,6 @@
F<Apache2/> subdir, in which case the two will always co-exist. But
this is not the most logical approach since 99% of users will want
only one generation of mod_perl core and 3rd party modules.
-
-
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org