[APACHE DOCUMENTATION]

Apache HTTP Server Version 1.3

Apache 1.3
Dynamic Shared Object (DSO)
Support

Originally written by
Ralf S. Engelschall <rse@apache.org>, April 1998

Background

On modern Unix derivatives there exists a nifty mechanism usually calleddynamic linking/loading of Dynamic Shared Objects (DSO) whichprovides a way to build a piece of program code in a special format forloading it at run-time into the address space of an executable program.

This loading can usually be done in two ways: Automatically by a systemprogram called ld.so when an executable program is started ormanually from within the executing program via a programmatic system interfaceto the Unix loader through the system calls dlopen()/dlsym().

In the first way the DSO's are usually called shared libraries orDSO libraries and named libfoo.so orlibfoo.so.1.2. They reside in a system directory (usually/usr/lib) and the link to the executable program is establishedat build-time by specifying -lfoo to the linker command. Thishard-codes library references into the executable program file so that atstart-time the Unix loader is able to locate libfoo.so in/usr/lib, in paths hard-coded via linker-options like-R or in paths configured via the environment variableLD_LIBRARY_PATH. It then resolves any (yet unresolved) symbols inthe executable program which are available in the DSO.

Symbols in the executable program are usually not referenced by the DSO(because it's a reusable library of general code) and hence no furtherresolving has to be done. The executable program has no need to do anything onits own to use the symbols from the DSO because the complete resolving is doneby the Unix loader. (In fact, the code to invoke ld.soChania hotel rooms is part ofthe run-time startup code which is linked into every executable program whichhas been bound non-static). The advantage of dynamic loading of common librarycode is obvious: the library code needs to be stored only once, in a systemlibrary like libc.so, saving disk space for every program.

In the second way the DSO's are usually called shared objects orDSO files and can be named with an arbitrary extension (although thecanonical name is foo.so). These files usually stay inside aprogram-specific directory and there is no automatically established link tothe executable program where they are used. Instead the executable programmanually loads the DSO at run-time into its address space viadlopen(). At this time no resolving of symbols from the DSO forthe executable program is done. But instead the Unix loader automaticallyresolves any (yet unresolved) symbols in the DSO from the set of symbolsexported by the executable program and its already loaded DSO libraries(especially all symbols from the ubiquitous libc.so). This waythe DSO gets knowledge of the executable program's symbol set as if it hadbeen statically linked with it in the first place.

Finally, to take advantage of the DSO's API the executable program has toresolve particular symbols from the DSO via dlsym() for later useinside dispatch tables etc. In other words: The executable program has tomanually resolve every symbol it needs to be able to use it. The advantage ofsuch a mechanism is that optional program parts need not be loaded (and thusdo not spend memory) until they are needed by the program in question. Whenrequired, these program parts can be loaded dynamically to extend the baseprogram's functionality.

Although this DSO mechanism sounds straightforward there is at least onedifficult step here: The resolving of symbols from the executable program forthe DSO when using a DSO to extend a program (the second way). Why? Because"reverse resolving" DSO symbols from the executable program's symbol set isagainst the library design (where the library has no knowledge about theprograms it is used by) and is neither available under all platforms norstandardized. In practice the executable program's global symbols are oftennot re-exported and thus not available for use in a DSO. Finding a way toforce the linker to export all global symbols is the main problem one has tosolve when using DSO for extending a program at run-time.

Practical Usage

The shared library approach is the typical one, because it is what the DSOmechanism was designed for, hence it is used for nearly all types of librariesthe operating system provides. On the other hand using shared objects forextending a program is not used by a lot of programs.

As of 1998 there are only a few software packages available which use theDSO mechanism to actually extend their functionality at run-time: Perl 5 (viaits XS mechanism and the DynaLoader module), Netscape Server, etc. Startingwith version 1.3, Apache joined the crew, because Apache already uses a moduleconcept to extend its functionality and internally uses a dispatch-list-basedapproach to link external modules into the Apache core functionality. So,Apache is really predestined for using DSO to load its modules at run-time.

As of Apache 1.3, the configuration system supports two optional featuresfor taking advantage of the modular DSO approach: compilation of the Apachecore program into a DSO library for shared usage and compilation of theApache modules into DSO files for explicit loading at run-time.

Implementation

The DSO support for loading individual Apache modules is based on a modulenamed mod_so.c which has to bestatically compiled into the Apache core. It is the only module besideshttp_core.c which cannot be put into a DSO itself(bootstrapping!). Practically all other distributed Apache modules then canthen be placed into a DSO by individually enabling the DSO build for them viaconfigure's --enable-shared option (see top-levelINSTALL file) or by changing the AddModule commandin your src/Configuration into a SharedModulecommand (see src/INSTALL file). After a module is compiled intoa DSO named mod_foo.so you can use mod_so's LoadModule command in yourhttpd.conf file to load this module at server startup or restart.

To simplify this creation of DSO files for Apache modules (especially forthird-party modules) a new support program named apxs (APacheeXtenSion) is available. It can be used to build DSO based modulesoutside of the Apache source tree. The idea is simple: Wheninstalling Apache the configure's make installprocedure installs the Apache C header files and puts the platform-dependentcompiler and linker flags for building DSO files into the apxsprogram. This way the user can use apxs to compile his Apachemodule sources without the Apache distribution source tree and without havingto fiddle with the platform-dependent compiler and linker flags for DSOsupport.

To place the complete Apache core program into a DSO library (only requiredon some of the supported platforms to force the linker to export the apachecore symbols -- a prerequisite for the DSO modularization) the ruleSHARED_CORE has to be enabled via configure's--enable-rule=SHARED_CORE option (see top-levelINSTALL file) or by changing the Rule command inyour Configuration file to Rule SHARED_CORE=yes (seesrc/INSTALL file). The Apache core code is then placed into a DSOlibrary named libhttpd.so. Because one cannot link a DSO againststatic libraries on all platforms, an additional executable program namedlibhttpd.ep is created which both binds this static code andprovides a stub for the main() function. Finally thehttpd executable program itself is replaced by a bootstrappingcode which automatically makes sure the Unix loader is able to load and startlibhttpd.ep by providing the LD_LIBRARY_PATH tolibhttpd.so.

Supported Platforms

Apache's src/Configure script currently has only limited butadequate built-in knowledge on how to compile DSO files, because as alreadymentioned this is heavily platform-dependent. Nevertheless all major Unixplatforms are supported. The definitive current state (May 1998) is this:

Usage Summary

To give you an overview of the DSO features of Apache 1.3, here is a shortand concise summary:

  1. Placing the Apache core code (all the stuff which usually forms thehttpd binary) into a DSO libhttpd.so, an executableprogram libhttpd.ep and a bootstrapping executable programhttpd (Notice: this is only required on some of the supportedplatforms to force the linker to export the Apache core symbols, which in turnis a prerequisite for the DSO modularization):

    • Build and install via configure (preferred):
      $ ./configure --prefix=/path/to/install              --enable-rule=SHARED_CORE ...$ make install
    • Build and install manually: 
      - Edit src/Configuration:  << Rule SHARED_CORE=default  >> Rule SHARED_CORE=yes  << EXTRA_CFLAGS=   >> EXTRA_CFLAGS= -DSHARED_CORE_DIR="/path/to/install/libexec"$ make $ cp src/libhttpd.so* /path/to/install/libexec/$ cp src/libhttpd.ep  /path/to/install/libexec/$ cp src/httpd        /path/to/install/bin/
  2. Build and install a distributed Apache module, saymod_foo.c, into its own DSO mod_foo.so:

    • Build and install via configure (preferred):
      $ ./configure --prefix=/path/to/install        --enable-shared=foo$ make install
    • Build and install manually: 
      - Edit src/Configuration:  << AddModule    modules/xxxx/mod_foo.o  >> SharedModule modules/xxxx/mod_foo.so$ make$ cp src/xxxx/mod_foo.so /path/to/install/libexec- Edit /path/to/install/etc/httpd.conf  >> LoadModule foo_module /path/to/install/libexec/mod_foo.so
  3. Build and install a third-party Apache module, saymod_foo.c, into its own DSO mod_foo.so

    • Build and install via configure (preferred):
      $ ./configure --add-module=/path/to/3rdparty/mod_foo.c         --enable-shared=foo$ make install
    • Build and install manually: 
      $ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/- Edit src/Configuration:  >> SharedModule modules/extra/mod_foo.so$ make$ cp src/xxxx/mod_foo.so /path/to/install/libexec- Edit /path/to/install/etc/httpd.conf  >> LoadModule foo_module /path/to/install/libexec/mod_foo.so

  4. Build and install a third-party Apache module, saymod_foo.c, into its own DSO mod_foo.so outsideof the Apache source tree:

    • Build and install via apxs: 
      $ cd /path/to/3rdparty$ apxs -c mod_foo.c$ apxs -i -a -n foo mod_foo.so

Advantages & Disadvantages

The above DSO based features of Apache 1.3 have the following advantages:

DSO has the following disadvantages:

Apache HTTP Server Version 1.3

Index
- | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |