stas 02/05/19 02:43:55
Modified: src/docs/2.0/user/compat compat.pod
Log:
- add a few notes
- add the missing markup
- do some reorg putting more desired things on top
Revision Changes Path
1.15 +126 -107 modperl-docs/src/docs/2.0/user/compat/compat.pod
Index: compat.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/compat/compat.pod,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- compat.pod 17 May 2002 17:59:55 -0000 1.14
+++ compat.pod 19 May 2002 09:43:55 -0000 1.15
@@ -1,6 +1,6 @@
=head1 NAME
-mod_perl 1.x versus mod_perl 2.x compatibility issues
+Migrating from mod_perl 1.x to mod_perl 2.x
=head1 Description
@@ -10,92 +10,117 @@
+=head1 Configuration Porting
-=head1 Code Porting from 1.x to 2.x
+To migrate the configuration files to the mod_perl 2.x syntax, you may
+need to do certain adjustments if you use any of the configuration
+directives listed in the following sections.
-mod_perl 2.x is trying hard to be back compatible with mod_perl
-1.x. However some things (mostly APIs) have been changed. In order to
-gain a complete compatibilty with 1.x while running under 2.x, you
-should load the compatibility module as early as possible:
+Remember that if you use any of the new directives, your configuration
+won't work anymore with mod_perl 1.x.
- use Apache::compat;
+=head2 C<PerlHandler>
-at the server startup. And unless there are forgotten things or bugs,
-your code should work without any changes under 2.x series.
+C<PerlHandler> was replaced with C<PerlResponseHandler>.
-If you have mod_perl 1.x and 2.x installed on the same system and the
-two use the same perl libraries directories (e.g. I</usr/lib/perl5>),
-make sure to load first the C<Apache2> module which will perform the
-necessary adjustments to C<@INC>.
+=head2 C<PerlSendHeader>
- use Apache2; # if you have 1.x and 2.x installed
- use Apache::compat;
+C<PerlSendHeader> was replaced with C<PerlOptions +/-ParseHeaders>
+directive.
-However, unless you want to keep the 1.x compatibility, you should try
-to remove the compatibility layer and adjust your code to work under
-2.x without it. You want to do it mainly for the performance
-improvement.
+ PerlSendHeader On => Options +ParseHeaders
+ PerlSendHeader Off => Options -ParseHeaders
-This document explains what APIs have changed and what new APIs should
-be used instead.
+=head2 C<PerlSetupEnv>
+C<PerlSetupEnv> was replaced with C<PerlOptions +/-SetupEnv>
+directive.
+ PerlSetupEnv On => Options +SetupEnv
+ PerlSetupEnv Off => Options -SetupEnv
+=head2 C<PerlTaintCheck>
+The tainting mode now can be turned on with:
+ PerlSwitches -T
+The default is I<Off>. You cannot turn it I<Off> once it's turned
+I<On>.
+=head2 C<PerlWarn>
-=head1 Configuration Directives
+Warnings now can be enabled globally with:
-To migrate the configuration files to the 2.x syntax, you may need to
-do certain adjustments if you use any of the configuration directives
-listed in the following sections.
+ PerlSwitches -w
-Remember that if you use any of the new directives you configuration
-won't work anymore with mod_perl 1.x.
-=head2 PerlHandler
-Replaced with C<PerlResponseHandler>.
-=head2 PerlSendHeader
-Replaced with C<PerlOptions +/-ParseHeaders> directive.
- PerlSendHeader On => Options +ParseHeaders
- PerlSendHeader Off => Options -ParseHeaders
+=head1 Code Porting
-=head2 PerlSetupEnv
+mod_perl 2.x is trying hard to be back compatible with mod_perl
+1.x. However some things (mostly APIs) have been changed. In order to
+gain a complete compatibilty with 1.x while running under 2.x, you
+should load the compatibility module as early as possible:
-Replaced with C<PerlOptions +/-SetupEnv> directive.
+ use Apache::compat;
- PerlSendHeader On => Options +SetupEnv
- PerlSendHeader Off => Options -SetupEnv
+at the server startup. And unless there are forgotten things or bugs,
+your code should work without any changes under 2.x series.
-=head2 PerlTaintCheck
+If you have mod_perl 1.x and 2.x installed on the same system and the
+two use the same perl libraries directories (e.g. I</usr/lib/perl5>),
+make sure to load first the C<Apache2> module which will perform the
+necessary adjustments to C<@INC>.
-Now can be turned on with:
+ use Apache2; # if you have 1.x and 2.x installed
+ use Apache::compat;
- PerlSwitches -T
+However, unless you want to keep the 1.x compatibility, you should try
+to remove the compatibility layer and adjust your code to work under
+2.x without it. You want to do it mainly for the performance
+improvement.
-The default is I<Off>. You cannot turn it I<Off> once it's turned
-I<On>.
+This document explains what APIs have changed and what new APIs should
+be used instead.
-=head2 PerlWarn
-Now can be turned on with:
+=head1 The C<Apache::Registry> Family
- PerlSwitches -w
+C<Apache::Registry>, C<Apache::PerlRun> and other modules from the
+registry family now live in the C<ModPerl::> namespace to avoid
+collisions with the versions from 1.x.
+
+To run the C<Apache::Registry> module from mod_perl 1.x you have to
+load C<Apache::compat> at the startup:
+
+ file:startup.pl:
+ ----------------
+ use Apache2; # if you have 1.x and 2.x installed
+ use Apache::compat ();
+ use lib ...; # to find 1.xx Apache::Registry
+then in I<httpd.conf>:
+ Alias /perl /path/to/perl/scripts
+ <Location /perl>
+ Options +ExecCGI
+ SetHandler perl-script
+ PerlResponseHandler Apache::Registry
+ </Location>
+Notice that C<Apache::compat> has to be loaded before C<CGI.pm> if the
+latter module is used.
+META: complete
-=head1 Apache::Constants
+=head1 C<Apache::Constants>
C<Apache::Constants> has been replaced by three classes:
@@ -128,11 +153,11 @@
-=head1 C<Apache::> functions
+=head1 C<Apache::>
-=head2 args()
+=head2 C<args()>
-$r->args() in 2.0 returns the query string without parsing and
+$r-E<gt>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.
@@ -141,20 +166,20 @@
XXX: When Apache::Request will be ported to 2.0, you can use its
params() and similar methods to do the parsing for you.
-=head2 chdir_file()
+=head2 C<chdir_file()>
XXX: Not implemented yet. And won't be implemented for the threaded
mpms, since chdir is not thread-safe.
-=head2 $r-E<gt>connection-E<gt>user
+=head2 C<$r-E<gt>connection-E<gt>user>
This method is deprecated in 1.x and $r-E<gt>user should be used
instead for both versions of mod_perl. C<Apache::user()> method is
available since mod_perl version 1.24_01.
-=head2 content()
+=head2 C<content()>
-$r->content() is not available in 2.0.
+$r-E<gt>content() is not available in 2.0.
XXX: the reason?
@@ -176,7 +201,7 @@
return $r->parse_args($buf)
}
-=head2 exit()
+=head2 C<exit()>
C<Apache::exit()> has been replaced with C<ModPerl::Util::exit()>,
which is a function (not a method) and accepts a single optional
@@ -185,7 +210,7 @@
See the L<ModPerl::Util> manpage for more information.
-=head2 finfo()
+=head2 C<finfo()>
XXX: not implemented yet. To be implemented. C<Apache::compat> handles
that for now with:
@@ -196,7 +221,7 @@
\*_;
}
-=head2 gensym()
+=head2 C<gensym()>
Since Perl 5.6.1 filehandlers are autovivified and there is no need
for C<Apache::gensym()> function, since now it can be done with:
@@ -206,7 +231,7 @@
Though the C function modperl_perl_gensym() is available for XS/C
extensions writers.
-=head2 header_in(), header_out() and err_header_out()
+=head2 C<header_in()>, C<header_out()> and C<err_header_out()>
C<header_in()>, C<header_out()> and C<err_header_out()> are not
available in 2.0. Use C<headers_in()>, C<headers_out()> and
@@ -224,7 +249,7 @@
-=head2 log_reason()
+=head2 C<log_reason()>
C<log_reason()> has been replaced with a set of dedicated functions:
C<Apache::RequestRec::log_error()>, C<Apache::ServerRec::log_error()>,
@@ -234,13 +259,13 @@
manpages for more information.
-=head2 module()
+=head2 C<module()>
C<Apache::module> has been replaced with the function
C<Apache::Module::loaded()>, which now accepts a single argument: the
module name.
-=head2 register_cleanup()
+=head2 C<register_cleanup()>
register_cleanup() has been replaced with
C<APR::Pool::cleanup_register()> which accepts the pool object as the
@@ -253,11 +278,23 @@
See the L<APR::Pool> manpage for more information.
-=head2 $r-E<gt>request
+=head2 C<$r-E<gt>request()>
Use C<Apache::request()>.
-=head2 send_fd() and send_fd_length()
+Notice that C<Apache-E<gt>request> is deprecated. It's error-prone
+and hurts performance when using threaded MPMs, since it has to use
+thread local storage.
+
+For any location that uses C<Apache-E<gt>request>, you need to
+configure:
+
+ <Location ...>
+ PerlOptions +GlobalRequest
+ ...
+ </Location>
+
+=head2 C<send_fd()> and C<send_fd_length()>
currently available only in the 1.x compatibility layer. The problem
is that Apache has changed the API and the its functionality. See the
@@ -265,7 +302,7 @@
XXX: needs a better resolution
-=head2 $r-E<gt>server_root_relative
+=head2 C<$r-E<gt>server_root_relative>
C<Apache::server_root_relative> is a function in 2.0.
@@ -282,19 +319,12 @@
The methods from module C<Apache::File> have been either moved to
other packages or removed.
-=head2 discard_request_body(), meets_conditions(), set_content_length(),
set_etag(), set_last_modified() and update_mtime()
-
-These functions now belong to the module L<Apache::Response>.
-
-=head2 mtime()
-
-mtime() now belongs to the module L<Apache::RequestRec>.
-=head2 open() and close()
+=head2 C<open()> and C<close()>
See the implementation in the module C<Apache::compat>.
-=head2 tmpfile()
+=head2 C<tmpfile()>
See C<File::Temp>, or the implementation in the module
C<Apache::compat>.
@@ -302,29 +332,44 @@
It was removed since Apache 2.0 doesn't have the API for this method
anymore.
-=head1 Apache::Util
+=head2 C<mtime()>
+
+mtime() now belongs to the module L<Apache::RequestRec>.
+
+
+=head2 C<discard_request_body()>, C<meets_conditions()>,
C<set_content_length()>, C<set_etag()>, C<set_last_modified()> and
C<update_mtime()>
+
+These functions now belong to the module L<Apache::Response>.
+
+
+
+
+
+
+=head1 C<Apache::Util>
A few C<Apache::Util> functions have changed their interface.
-=head2 Apache::Util::size_string
+=head2 C<Apache::Util::size_string>
C<Apache::Util::size_string> has been replaced with
C<APR::String::format_size>, which returns formatted strings of only 4
characters long. See the L<C<APR::String>> manpage for more
information.
-=head2 Apache::Util::unescape_uri()
+=head2 C<Apache::Util::unescape_uri()>
C<Apache::Util::unescape_uri()> is now C<Apache::unescape_url()>.
-=head1 Apache::URI
+=head1 C<Apache::URI>
-=head2 Apache::URI::parse
+=head2 C<Apache::URI-E<gt>parse($r, [$uri])>
-C<Apache::URI::parse()> has been replaced with C<APR::URI->parse()>,
-which is invoked as:
+C<Apache::URI-E<gt>parse()> has been replaced with
+C<APR::URI-E<gt>parse()>, which is invoked as:
- APR::URI->parse($r->pool, $uri);
+ my $curl = $r->construct_url;
+ APR::URI->parse($r->pool, $curl);
See the L<APR::URI> manpage for more information.
@@ -364,37 +409,11 @@
subroutine attributes.
-=head1 Apache::Registry and Apache::PerlRun and Other mod_cgi Emulators
-C<Apache::Registry>, C<Apache::PerlRun> and other modules from the
-registry family now live in the C<ModPerl::> namespace to avoid
-collisions with the versions from 1.x.
-To run the C<Apache::Registry> module from mod_perl 1.x you have to
-load C<Apache::compat> at the startup:
-
- file:startup.pl:
- ----------------
- use Apache2; # if you have 1.x and 2.x installed
- use Apache::compat ();
- use lib ...; # to find 1.xx Apache::Registry
-
-then in I<httpd.conf>:
-
- Alias /perl /path/to/perl/scripts
- <Location /perl>
- Options +ExecCGI
- SetHandler perl-script
- PerlResponseHandler Apache::Registry
- </Location>
-
-Notice that C<Apache::compat> has to be loaded before C<CGI.pm> if the
-latter module is used.
-
-META: complete
-=head1 Apache::StatINC
+=head1 C<Apache::StatINC>
C<Apache::StatINC> has been replaced by C<Apache::Reload>.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
