svn commit: r123762 - /perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod

[st...@apache.org]

Author: stas
Date: Thu Dec 30 18:53:33 2004
New Revision: 123762

URL: http://svn.apache.org/viewcvs?view=rev&rev=123762
Log:
new sub-section: The Conflict of mp1 vs mp2 vs mp22 vs ... vs mpNN


Modified:
   perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod

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&rev=123762&p1=perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod&r1=123761&p2=perl/modperl/docs/trunk/src/docs/2.0/user/porting/porting.pod&r2=123762
==============================================================================
--- 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	Thu Dec 30 18:53:33 2004
@@ -1470,6 +1470,343 @@
 
 
 
+=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
+
+
+=head2 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).
+
+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>.
+
+
+=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
+
+
+
+=head2 Distributors
+
+Distributors should mark the different generations of mod_perl core as
+conflicting, so only one version can be installed using the binary
+package. Users requiring more than one installation should do a manual
+install.
+
+In order to have any of the 3rd party modperl modules installed users
+need to have the correct modperl package installed. So there is no
+need to mark the 3rd party modules as conflicting, since their most
+important prerequisite (the modperl-core) is already handling that.
+
+Of course packagers can decide to make the two generation packages as
+non-conflicting, by building all mp2 core and 3rd party modules into
+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.
+
+
+
+
+=head2 The CPAN Shell
+
+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
+
+If you have only mp2 and you didn't ask to install it under the
+F<Apache2/> subdirectory, no special invocation technique is required.
+
+
+
+
 
 =head1 Maintainers
 

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org