From: Joshua Slive Date: Wed, 19 Sep 2001 14:49:34 +0000 (+0000) Subject: Finish some cleanup that Ryan started on dso.html: X-Git-Tag: 2.0.26~217 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=04d0f0e2863a86be6ffa78290da6587def09aa73;p=thirdparty%2Fapache%2Fhttpd.git Finish some cleanup that Ryan started on dso.html: - Add a sumary, index, ext - put the most important stuff at the top - remove some obsolete stuff git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91086 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/dso.html b/docs/manual/dso.html index 28b4b440fa4..3fcadb0b586 100644 --- a/docs/manual/dso.html +++ b/docs/manual/dso.html @@ -1,6 +1,6 @@ -Apache 2.0 Dynamic Shared Object (DSO) support +Dynamic Shared Object (DSO) support @@ -11,23 +11,132 @@ VLINK="#000080" ALINK="#FF0000" > -
-
-

-Apache 2.0
-Dynamic Shared Object (DSO)
-Support +Dynamic Shared Object (DSO) Support

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

The Apache HTTP Server is a modular program where the administrator +can choose the functionality to include in the server by selecting a +set of modules. The modules can be statically compiled into the +httpd binary when the server is built. Alternatively, +modules can be compiled as Dynamic Shared Objects (DSOs) that exist +separately from the main httpd binary file. DSO modules +may be compiled at the time the server is built, or they may be +compiled and added at a later time using the Apache Extension Tool (apxs).

+ +

This document describes how to use DSO modules as well as the theory +behind their use.

+ + + +
+ + +
+Related Modules

+ +mod_so
+ +		 +Related Directives

+ +LoadModule
+ +
+ +

Implementation

+ +

The DSO support for loading individual Apache modules is based on a module +named mod_so.c which must be +statically compiled into the Apache core. It is the only module besides +core.c which cannot be put into a DSO itself. +Practically all other distributed Apache modules then can +then be placed into a DSO by individually enabling the DSO build for them via +configure's --enable-module=shared option +(see top-level INSTALL file). After a module is compiled into +a DSO named mod_foo.so you can use mod_so's LoadModule command in your +httpd.conf file to load this module at server startup or restart. + +

To simplify this creation of DSO files for Apache modules +(especially for third-party modules) a new support program named apxs (APache eXtenSion) is +available. It can be used to build DSO based modules outside +of the Apache source tree. The idea is simple: When installing +Apache the configure's make install +procedure installs the Apache C header files and puts the +platform-dependent compiler and linker flags for building DSO files +into the apxs program. This way the user can use +apxs to compile his Apache module sources without the +Apache distribution source tree and without having to fiddle with the +platform-dependent compiler and linker flags for DSO support. + +

Usage Summary

+ +

To give you an overview of the DSO features of Apache 2.0, here is a short +and concise summary: + +

    + +
  1. Build and install a distributed Apache module, say +mod_foo.c, into its own DSO mod_foo.so: + +
    +
    +$ ./configure --prefix=/path/to/install
+        --enable-foo=shared
+$ make install
+
    +
    + +
  2. Build and install a third-party Apache module, say +mod_foo.c, into its own DSO mod_foo.so: -
+
+
+$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
+        --enable-foo=shared
+$ make install
+
+
-

Background

+
  • Configure Apache for later installation of shared modules: +
    +
    +$ ./configure --enable-so
+$ make install
+
    +
    + +
  • Build and install a third-party Apache module, say +mod_foo.c, into its own DSO mod_foo.so outside +of the Apache source tree using apxs: +
    +
    +$ cd /path/to/3rdparty
+$ apxs -c mod_foo.c
+$ apxs -i -a -n foo mod_foo.so
+
    +
    + + + +

    In all cases, once the shared module is compiled, you must use a LoadModule directive +in httpd.conf to tell Apache to activate the module. + + + +

    Background

    On modern Unix derivatives there exists a nifty mechanism usually called dynamic linking/loading of Dynamic Shared Objects (DSO) which @@ -95,8 +204,6 @@ not re-exported and thus not available for use in a DSO. Finding a way to force the linker to export all global symbols is the main problem one has to solve 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 DSO mechanism was designed for, hence it is used for nearly all types of libraries the operating system provides. On the other hand using shared objects for @@ -110,148 +217,10 @@ concept to extend its functionality and internally uses a dispatch-list-based approach to link external modules into the Apache core functionality. So, Apache is really predestined for using DSO to load its modules at run-time. -

    Implementation

    - -

    The DSO support for loading individual Apache modules is based on a module -named mod_so.c which has to be -statically compiled into the Apache core. It is the only module besides -core.c which cannot be put into a DSO itself -(bootstrapping!). Practically all other distributed Apache modules then can -then be placed into a DSO by individually enabling the DSO build for them via -configure's --enable-module=shared option -(see top-level INSTALL file). After a module is compiled into -a DSO named mod_foo.so you can use mod_so's LoadModule command in your -httpd.conf file to load this module at server startup or restart. - -

    To simplify this creation of DSO files for Apache modules -(especially for third-party modules) a new support program named apxs (APache eXtenSion) is -available. It can be used to build DSO based modules outside -of the Apache source tree. The idea is simple: When installing -Apache the configure's make install -procedure installs the Apache C header files and puts the -platform-dependent compiler and linker flags for building DSO files -into the apxs program. This way the user can use -apxs to compile his Apache module sources without the -Apache distribution source tree and without having to fiddle with the -platform-dependent compiler and linker flags for DSO support. - -

    Supported Platforms

    - -

    Apache's src/Configure script currently has only limited but -adequate built-in knowledge on how to compile DSO files, because as already -mentioned this is heavily platform-dependent. Nevertheless all major Unix -platforms are supported. The definitive current state (May 1999) is this: - -

    -

      -
    • Out-of-the-box supported platforms:
      -(actually tested versions in parenthesis) - -
      -o  FreeBSD            (2.1.5, 2.2.x, 3.x, 4.x)
-o  OpenBSD            (2.x)
-o  NetBSD             (1.3.1)
-o  BSDI               (3.x, 4.x)
-o  Linux              (Debian/1.3.1, RedHat/4.2)
-o  Solaris            (2.4, 2.5, 2.6, 2.7)
-o  SunOS              (4.1.3)
-o  Digital UNIX       (4.0)
-o  IRIX               (5.3, 6.2)
-o  HP/UX              (10.20)
-o  UnixWare           (2.01, 2.1.2)
-o  SCO                (5.0.4)
-o  AIX                (3.2, 4.1.5, 4.2, 4.3)
-o  ReliantUNIX/SINIX  (5.43)
-o  SVR4               (-)
-o  Mac OS X Server    (1.0)
-o  Mac OS             (10.0 preview 1)
-o  OpenStep/Mach      (4.2)
-o  DGUX               (??)
-o  NetWare            (5.1)
-
      - -

      -

    • Explicitly unsupported platforms: - -
      -o  Ultrix             (no dlopen-style interface under this platform)
-
      - -
    - -

    Usage Summary

    - -

    To give you an overview of the DSO features of Apache 2.0, here is a short -and concise summary: - -

      - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --prefix=/path/to/install ...
-$ make install
-
        -
        -
      - -
    1. Build and install a distributed Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --prefix=/path/to/install
-        --enable-foo=shared
-$ make install
-
        -
        -
      - -
    2. Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
-        --enable-foo=shared
-$ make install
-
        -
        -
      - -

      -

    3. Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so outside -of 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

    +

    Advantages and Disadvantages

    -

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

    The above DSO based features have the following advantages:

    • The server package is more flexible at run-time because the actual server @@ -305,6 +274,5 @@ $ apxs -i -a -n foo mod_foo.so
    -
    • diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en index 28b4b440fa4..3fcadb0b586 100644 --- a/docs/manual/dso.html.en +++ b/docs/manual/dso.html.en @@ -1,6 +1,6 @@ -Apache 2.0 Dynamic Shared Object (DSO) support +Dynamic Shared Object (DSO) support @@ -11,23 +11,132 @@ VLINK="#000080" ALINK="#FF0000" > -
    -
    -

    -Apache 2.0
    -Dynamic Shared Object (DSO)
    -Support +Dynamic Shared Object (DSO) Support

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

    The Apache HTTP Server is a modular program where the administrator +can choose the functionality to include in the server by selecting a +set of modules. The modules can be statically compiled into the +httpd binary when the server is built. Alternatively, +modules can be compiled as Dynamic Shared Objects (DSOs) that exist +separately from the main httpd binary file. DSO modules +may be compiled at the time the server is built, or they may be +compiled and added at a later time using the Apache Extension Tool (apxs).

    + +

    This document describes how to use DSO modules as well as the theory +behind their use.

    + + + +
    + + +
    +Related Modules

    + +mod_so
    + +    		 +Related Directives

    + +LoadModule
    + +
    + +

    Implementation

    + +

    The DSO support for loading individual Apache modules is based on a module +named mod_so.c which must be +statically compiled into the Apache core. It is the only module besides +core.c which cannot be put into a DSO itself. +Practically all other distributed Apache modules then can +then be placed into a DSO by individually enabling the DSO build for them via +configure's --enable-module=shared option +(see top-level INSTALL file). After a module is compiled into +a DSO named mod_foo.so you can use mod_so's LoadModule command in your +httpd.conf file to load this module at server startup or restart. + +

    To simplify this creation of DSO files for Apache modules +(especially for third-party modules) a new support program named apxs (APache eXtenSion) is +available. It can be used to build DSO based modules outside +of the Apache source tree. The idea is simple: When installing +Apache the configure's make install +procedure installs the Apache C header files and puts the +platform-dependent compiler and linker flags for building DSO files +into the apxs program. This way the user can use +apxs to compile his Apache module sources without the +Apache distribution source tree and without having to fiddle with the +platform-dependent compiler and linker flags for DSO support. + +

    Usage Summary

    + +

    To give you an overview of the DSO features of Apache 2.0, here is a short +and concise summary: + +

      + +
    1. Build and install a distributed Apache module, say +mod_foo.c, into its own DSO mod_foo.so: + +
      +
      +$ ./configure --prefix=/path/to/install
+        --enable-foo=shared
+$ make install
+
      +
      + +
    2. Build and install a third-party Apache module, say +mod_foo.c, into its own DSO mod_foo.so: -
    +
    +
    +$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
+        --enable-foo=shared
+$ make install
+
    +
    -

    Background

    +
  • Configure Apache for later installation of shared modules: +
    +
    +$ ./configure --enable-so
+$ make install
+
    +
    + +
  • Build and install a third-party Apache module, say +mod_foo.c, into its own DSO mod_foo.so outside +of the Apache source tree using apxs: +
    +
    +$ cd /path/to/3rdparty
+$ apxs -c mod_foo.c
+$ apxs -i -a -n foo mod_foo.so
+
    +
    + + + +

    In all cases, once the shared module is compiled, you must use a LoadModule directive +in httpd.conf to tell Apache to activate the module. + + + +

    Background

    On modern Unix derivatives there exists a nifty mechanism usually called dynamic linking/loading of Dynamic Shared Objects (DSO) which @@ -95,8 +204,6 @@ not re-exported and thus not available for use in a DSO. Finding a way to force the linker to export all global symbols is the main problem one has to solve 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 DSO mechanism was designed for, hence it is used for nearly all types of libraries the operating system provides. On the other hand using shared objects for @@ -110,148 +217,10 @@ concept to extend its functionality and internally uses a dispatch-list-based approach to link external modules into the Apache core functionality. So, Apache is really predestined for using DSO to load its modules at run-time. -

    Implementation

    - -

    The DSO support for loading individual Apache modules is based on a module -named mod_so.c which has to be -statically compiled into the Apache core. It is the only module besides -core.c which cannot be put into a DSO itself -(bootstrapping!). Practically all other distributed Apache modules then can -then be placed into a DSO by individually enabling the DSO build for them via -configure's --enable-module=shared option -(see top-level INSTALL file). After a module is compiled into -a DSO named mod_foo.so you can use mod_so's LoadModule command in your -httpd.conf file to load this module at server startup or restart. - -

    To simplify this creation of DSO files for Apache modules -(especially for third-party modules) a new support program named apxs (APache eXtenSion) is -available. It can be used to build DSO based modules outside -of the Apache source tree. The idea is simple: When installing -Apache the configure's make install -procedure installs the Apache C header files and puts the -platform-dependent compiler and linker flags for building DSO files -into the apxs program. This way the user can use -apxs to compile his Apache module sources without the -Apache distribution source tree and without having to fiddle with the -platform-dependent compiler and linker flags for DSO support. - -

    Supported Platforms

    - -

    Apache's src/Configure script currently has only limited but -adequate built-in knowledge on how to compile DSO files, because as already -mentioned this is heavily platform-dependent. Nevertheless all major Unix -platforms are supported. The definitive current state (May 1999) is this: - -

    -

      -
    • Out-of-the-box supported platforms:
      -(actually tested versions in parenthesis) - -
      -o  FreeBSD            (2.1.5, 2.2.x, 3.x, 4.x)
-o  OpenBSD            (2.x)
-o  NetBSD             (1.3.1)
-o  BSDI               (3.x, 4.x)
-o  Linux              (Debian/1.3.1, RedHat/4.2)
-o  Solaris            (2.4, 2.5, 2.6, 2.7)
-o  SunOS              (4.1.3)
-o  Digital UNIX       (4.0)
-o  IRIX               (5.3, 6.2)
-o  HP/UX              (10.20)
-o  UnixWare           (2.01, 2.1.2)
-o  SCO                (5.0.4)
-o  AIX                (3.2, 4.1.5, 4.2, 4.3)
-o  ReliantUNIX/SINIX  (5.43)
-o  SVR4               (-)
-o  Mac OS X Server    (1.0)
-o  Mac OS             (10.0 preview 1)
-o  OpenStep/Mach      (4.2)
-o  DGUX               (??)
-o  NetWare            (5.1)
-
      - -

      -

    • Explicitly unsupported platforms: - -
      -o  Ultrix             (no dlopen-style interface under this platform)
-
      - -
    - -

    Usage Summary

    - -

    To give you an overview of the DSO features of Apache 2.0, here is a short -and concise summary: - -

      - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --prefix=/path/to/install ...
-$ make install
-
        -
        -
      - -
    1. Build and install a distributed Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --prefix=/path/to/install
-        --enable-foo=shared
-$ make install
-
        -
        -
      - -
    2. Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so - -

      -

        -
      • Build and install via configure: -
        -
        -$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
-        --enable-foo=shared
-$ make install
-
        -
        -
      - -

      -

    3. Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so outside -of 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

    +

    Advantages and Disadvantages

    -

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

    The above DSO based features have the following advantages:

    • The server package is more flexible at run-time because the actual server @@ -305,6 +274,5 @@ $ apxs -i -a -n foo mod_foo.so
    -