Author: randyk Date: Thu Apr 7 11:23:45 2005 New Revision: 160425 URL: http://svn.apache.org/viewcvs?view=rev&rev=160425 Log: Start of a document discussing the effects of the recent renaming changes.
Added: perl/modperl/docs/trunk/src/docs/2.0/rename.pod Modified: perl/modperl/docs/trunk/src/docs/2.0/config.cfg Modified: perl/modperl/docs/trunk/src/docs/2.0/config.cfg URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/config.cfg?view=diff&r1=160424&r2=160425 ============================================================================== --- perl/modperl/docs/trunk/src/docs/2.0/config.cfg (original) +++ perl/modperl/docs/trunk/src/docs/2.0/config.cfg Thu Apr 7 11:23:45 2005 @@ -14,6 +14,11 @@ abstract => <<EOB, A collection of the documents specific to the mod_perl 2.0 generation. EOB + + chapters => [qw( + rename.pod + )], + docsets => [qw( user os Added: perl/modperl/docs/trunk/src/docs/2.0/rename.pod URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/rename.pod?view=auto&rev=160425 ============================================================================== --- perl/modperl/docs/trunk/src/docs/2.0/rename.pod (added) +++ perl/modperl/docs/trunk/src/docs/2.0/rename.pod Thu Apr 7 11:23:45 2005 @@ -0,0 +1,164 @@ +=head1 NAME + +mod_perl 2.0 renaming + +=head1 Description + +This document discusses the effects of the decision to rename +parts of the mod_perl API. + +=head1 Synopsis + +During a sequence of release candidates leading up to +the official release of mod_perl 2, +in late December, 2004 there was considerable discussion +regarding the choice of namespaces for the 2.0 API. +The main concern expressed was that some of the +C<Apache::*> modules used in mod_perl 2 had the same names +as those in mod_perl 1. After a lively and, at times, +heated debate, a proposal was made to rename parts of +the mod_perl 2 API - see the thread at +L<http://marc.theaimsgroup.com/?t=111135037100002&r=1&w=2>. +This proposal was subsequently voted on and then adopted. + +=head1 Changes + +The main changes involved in this renaming are as follows. + +=over + +=item * + +Rename all C<Apache::*> modules to C<Apache2::*>, save for +the following exceptions: + +=over 4 + +=item * + +The C<Apache::Test*> modules in the C<Apache-Test> distribution +are unaffected by this rename. + +=item * + +Constants under the C<Apache::*> namespace, +such as C<Apache::OK>, are now called as C<Apache2::Const::*> +(for example, C<Apache2::Const::OK>). + +=item * + +Constants under the C<APR::*> namespace, +such as C<APR::SUCCESS>, are now called as C<APR::Const::*> +(for example, C<APR::Const::SUCCESS>). + +=back + +=item * + +C<Apache-E<gt>request()> has been renamed to +C<Apache2::RequestUtil-E<gt>request()>. + +=item * + +C<Apache-E<gt>server()> has been renamed to +C<Apache2::ServerUtil-E<gt>server()>. + +=item * + +Rename C<mod_perl.pm> to C<mod_perl2.pm> + +=item * + +Discontinue the practice of installing mod_perl in a +relative F<Apache2> subdirectory, so that the use +of C<Apache2.pm> to adjust C<@INC> is no longer needed. + +=back + +Concurrent with these changes, a decision was also made to +refuse to install mod_perl 2 in the same Perl tree as any +installed mod_perl 2 package of version prior to 1.999_22. + +=head1 Effects + +The mod_perl developers did not take lightly the effects of +changing the API at such a late stage in the development cycle. +For most users the change to the new API should be relatively +straightforward: + +=over + +=item * + +Before installing mod_perl 2, either remove an earlier +mod_perl 2 installation (prior to 1.999022), or else choose +to install the new version in a different area. + +=item * + +If building mod_perl 2 from source, the C<Makefile.PL> argument +of C<MP_INST_APACHE2> is no longer supported. + +=item * + +Replace the use of + + use Apache::SomeCoreModule; + +in a script or module by + + use Apache2::SomeCoreModule; + +Similarly, an Apache directive + + PerlModule Apache::SomeCoreModule + +in an F<httpd.conf> file should be replace by + + PerlModule Apache2::SomeCoreModule + +A similar substitution from C<mod_perl> to C<mod_perl2> should +be made in similar places. + +=item * + +Replace the use of constants C<Apache::*> by C<Apache2::Const::*> +and C<APR::*> by C<APR::Const::*>. + +=item * + +Remove any occurrences of + + use Apache2; + +in a script or module, as well as + + PerlModule Apache2 + +in an Apache configuration file. + +=item * + +In a script or module, replace +C<Apache-E<gt>request()> by C<Apache2::RequestUtil-E<gt>request()> +and C<Apache-E<gt>server()> by C<Apache2::ServerUtil-E<gt>server()>. + +=back + +Beginning with mod_perl-1.999_22, an environment variable +C<$ENV{MOD_PERL_API_VERSION}> has been added to specify +which mod_perl version is being used. + +=head1 See Also + +The directions for +L<installing mod_perl 2.0 |docs::2.0::user::install::install>. +Help is also available through the archives of and subscribing to +the L<mod_perl mailing list|maillist::modperl>. + +=head1 Authors + +L<The mod_perl development team and numerous +contributors|about::contributors::people>. + +=cut --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]