DSO support for SVR4-based Unix platforms
 =========================================

What it provides:
-----------------

This patch is another milestone in the DSO support for Apache 1.3. It adds
Dynamic Shared Object (DSO) support for mostly all SVR4-based Unix platforms
(We cannot test all of them of course, but Martin has at least tested it under
SINIX-SVR4). Why is this patch a little bit larger then one would expect?
Mostly because this support goes hand in hand by providing a special variant
of the Apache core program. Read on if you are interested.

Background:
-----------

Usually the DSO mechanism was designed to be used for loading library code
dynamically into the address space of a running program. Here the library code
is a stand-alone program which has no knowledge of the program it is loaded
into. Technically speaking this means that no symbols of the loading program
are references in the DSO. The resolving is done only the other way: Symbols
of the library are resolved for the program (either automatically by ld.so
when one uses DSO-based libraries or manually via dlopen()/dlsym() when using
DSO-based program extensions.

Now when you use the latter situation the DSO usually contains a program
extension. This extension usually uses symbols from the program it extends:
from the API. Same here for Apache: The core provides API symbols and the
extensions are Apache modules which use those symbols. Now comes the problem:
when you load a DSO via dlopen() the loader has to resolve the symbols in this
DSO. Symbols from other DSO-based libraries can be resolved the same way ld.so
does. No problem. But to be able to resolve the API symbols the loader must be
able to access them. Technically speaking one would say the API symbols have
to be "exported". This is not the same as just being a "global" symbol,
although a lot of platforms treat this equally. Actually it is this way: When
the linker creates an executable program it does not treats global symbols as
exported symbols. But because this is needed for extending the program via
DSO, modern linkers usually either provide a flag (-rdynamic under Linux,
etc.) or are smart enough to do the exportation automatically (Solaris,
FreeBSD, etc.)

But as life goes, there are linkers out there who neither provide a flag to
force exportation nor are smart enough to do it automatically. FOR INSTANCE
THE LINKER UNDER SVR4! That's the problem this patch has to solve.

Solution:
---------

We have to make sure the global symbols from the Apache core program are
forced to be exported by the linker. The obvious way is this: Create a
dummy.so with dummy references for _ALL_ global symbols and link httpd against
this DSO. This works but has some drawbacks: You have to make sure the dummy.c
source is always in sync with the list of global symbols (ARGL!) and you have
to make sure the Unix loader can find "dummy.so" when starting httpd (Hmmmm).
So Martin and I've searched for a better solution. And because I'm a Perl
hacker I immediately tried to figure out why Perl is able to use the DSO
mechanism without problems under SVR4 while Apache has such problems.  The
answer: Perl 5 uses a nifty trick. As we already know when program code stays
in a DSO the global symbols have to be exportable. So, when we put the
complete Apache core (the stuff httpd is usually build from) into a DSO we are
finished. Because this is both portable and causes no sideeffects like having
to sync a dummy.c source, etc.

While the theory is simple, the correct solution was not such simple. Martin
and I needed some iterations to provide this patch because we wanted to make
it perfect and clean. That's why it's a little bit longer....

The Patch:
----------

The patch does the following:

1. It introduces a new Rule: SHARED_CORE

2. It makes the main() function from http_main.c configurable
   and sets it to ap_main if SHARED_CORE is active.

3. It adds two additional stand-alone main() functions to
   http_main.c which are triggered by SHARED_CORE_BOOTSTRAP and
   SHARED_CORE_TIESTATIC.

4. It splits the TARGET in Makefile.tmpl into subtargets.
   One for the standard way of creating just httpd from the .a files. And one
   for creating the alternative tuple: httpd/libhttpd.ep/libhttpd.so. The
   first one is SHARED_CORE_BOOTSTRAP+http_main.c, the second one is
   SHARED_CORE_TIESTATIC+httpd_main.c and the third one are the .a files
   which usually form the httpd.

5. The DSO section in Configure was extended to force
   SHARED_CORE under those platforms like SVR4 which essentially
   require SHARED_CORE to provide the SHARED_MODULE stuff. Bingo!

6. Some minor tweaks to APACI etc. to automatically install
   the SHARED_CORE generated stuff.

Of course the complete stuff is disabled per default, so you don't see
anything from it if SHARED_CORE is not activated.  But just for fun you even
can use it under platforms who do not require it. But currently you gain
nothing here.

I've tested this stuff under FreeBSD, Linux and Solaris to make sure none of
the existing stuff gets broken.  Martin has tested it under various SVR4
platforms to make sure it really solves our DSO problem for restrictive
platforms like SVR4. The chance is high that this way we even can provide DSO
support under AIX in the future.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/1.3.x@80857 13f79535-47bb-0310-9956-ffa450edef68