From: Ryan Bloom Date: Mon, 3 Sep 2001 16:31:27 +0000 (+0000) Subject: Update the DSO docs for Apache 2.0 X-Git-Tag: 2.0.26~335 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9f4a4c0ed9345ebb550e8d2ba85335a70f10b2df;p=apache Update the DSO docs for Apache 2.0 PR: 6879 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@90880 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/dso.html b/docs/manual/dso.html index bff578e444..28b4b440fa 100644 --- a/docs/manual/dso.html +++ b/docs/manual/dso.html @@ -1,6 +1,6 @@ -Apache 1.3 Dynamic Shared Object (DSO) support +Apache 2.0 Dynamic Shared Object (DSO) support @@ -17,7 +17,7 @@

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

@@ -110,23 +110,16 @@ 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. -

As of Apache 1.3, the configuration system supports two optional features -for taking advantage of the modular DSO approach: compilation of the Apache -core program into a DSO library for shared usage and compilation of the -Apache modules into DSO files for explicit loading 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 -http_core.c which cannot be put into a DSO itself +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-shared option (see top-level -INSTALL file) or by changing the AddModule command -in your src/Configuration into a SharedModule -command (see src/INSTALL file). After a module is compiled into +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 @@ -145,23 +138,6 @@ into the apxs program. This way the user can use Apache distribution source tree and without having to fiddle with the platform-dependent compiler and linker flags for DSO support. -

To place the complete Apache core program into a DSO library (only required -on some of the supported platforms to force the linker to export the apache -core symbols -- a prerequisite for the DSO modularization) the rule -SHARED_CORE has to be enabled via configure's ---enable-rule=SHARED_CORE option (see top-level -INSTALL file) or by changing the Rule command in -your Configuration file to Rule SHARED_CORE=yes (see -src/INSTALL file). The Apache core code is then placed into a DSO -library named libhttpd.so. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -libhttpd.ep is created which both binds this static code and -provides a stub for the main() function. Finally the -httpd executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -libhttpd.ep by providing the LD_LIBRARY_PATH to -libhttpd.so. -

Supported Platforms

Apache's src/Configure script currently has only limited but @@ -208,43 +184,20 @@ o Ultrix (no dlopen-style interface under this platform)

Usage Summary

-

To give you an overview of the DSO features of Apache 1.3, here is a short +

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

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

      -
    • Build and install via configure (preferred): +
    • Build and install via configure: 
      -$ ./configure --prefix=/path/to/install
-              --enable-rule=SHARED_CORE ...
+$ ./configure --prefix=/path/to/install ...
 $ 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/modules\"
-$ make 
-$ cp src/libhttpd.so* /path/to/install/modules/
-$ cp src/libhttpd.ep  /path/to/install/modules/
-$ cp src/httpd        /path/to/install/bin/
-
      -
  2. Build and install a distributed Apache module, say @@ -252,27 +205,14 @@ $ cp src/httpd /path/to/install/bin/

      -
    • Build and install via configure (preferred): +
    • Build and install via configure: 
       $ ./configure --prefix=/path/to/install
-        --enable-shared=foo
+        --enable-foo=shared
 $ 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/modules
-- Edit /path/to/install/etc/httpd.conf
-  >> LoadModule foo_module /path/to/install/modules/mod_foo.so
-
      -
  3. Build and install a third-party Apache module, say @@ -280,27 +220,14 @@ $ cp src/xxxx/mod_foo.so /path/to/install/modules

      -
    • Build and install via configure (preferred): +
    • Build and install via configure: 
      -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c 
-        --enable-shared=foo
+$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
+        --enable-foo=shared
 $ 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/modules
-- Edit /path/to/install/etc/httpd.conf
-  >> LoadModule foo_module /path/to/install/modules/mod_foo.so
-
      -

    @@ -324,14 +251,14 @@ $ apxs -i -a -n foo mod_foo.so

    Advantages & Disadvantages

    -

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

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

    • The server package is more flexible at run-time because the actual server process can be assembled at run-time via LoadModule httpd.conf configuration commands instead of - Configuration AddModule commands at build-time. + configure options at build-time. For instance this way one is able to run different server instances (standard & SSL version, minimalistic & powered up version [mod_perl, PHP3], etc.) with only one Apache installation. @@ -372,20 +299,9 @@ $ apxs -i -a -n foo mod_foo.so and all other dynamic or static libraries used by the Apache core, or from static library archives (libfoo.a) containing position independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself via dlopen() or enabling the - SHARED_CHAIN rule while building Apache when your platform - supports linking DSO files against DSO libraries. + sure the Apache core itself already contains a reference to it or loading + the code yourself via dlopen().

      -

    • Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the SHARED_CORE feature because this - way the global symbols are forced to be exported. As a consequence the - Apache src/Configure script automatically enforces - SHARED_CORE on these platforms when DSO features are used in - the Configuration file or on the configure command line.
    diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en index bff578e444..28b4b440fa 100644 --- a/docs/manual/dso.html.en +++ b/docs/manual/dso.html.en @@ -1,6 +1,6 @@ -Apache 1.3 Dynamic Shared Object (DSO) support +Apache 2.0 Dynamic Shared Object (DSO) support @@ -17,7 +17,7 @@

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

    @@ -110,23 +110,16 @@ 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. -

    As of Apache 1.3, the configuration system supports two optional features -for taking advantage of the modular DSO approach: compilation of the Apache -core program into a DSO library for shared usage and compilation of the -Apache modules into DSO files for explicit loading 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 -http_core.c which cannot be put into a DSO itself +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-shared option (see top-level -INSTALL file) or by changing the AddModule command -in your src/Configuration into a SharedModule -command (see src/INSTALL file). After a module is compiled into +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 @@ -145,23 +138,6 @@ into the apxs program. This way the user can use Apache distribution source tree and without having to fiddle with the platform-dependent compiler and linker flags for DSO support. -

    To place the complete Apache core program into a DSO library (only required -on some of the supported platforms to force the linker to export the apache -core symbols -- a prerequisite for the DSO modularization) the rule -SHARED_CORE has to be enabled via configure's ---enable-rule=SHARED_CORE option (see top-level -INSTALL file) or by changing the Rule command in -your Configuration file to Rule SHARED_CORE=yes (see -src/INSTALL file). The Apache core code is then placed into a DSO -library named libhttpd.so. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -libhttpd.ep is created which both binds this static code and -provides a stub for the main() function. Finally the -httpd executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -libhttpd.ep by providing the LD_LIBRARY_PATH to -libhttpd.so. -

    Supported Platforms

    Apache's src/Configure script currently has only limited but @@ -208,43 +184,20 @@ o Ultrix (no dlopen-style interface under this platform)

    Usage Summary

    -

    To give you an overview of the DSO features of Apache 1.3, here is a short +

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

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

        -
      • Build and install via configure (preferred): +
      • Build and install via configure: 
        -$ ./configure --prefix=/path/to/install
-              --enable-rule=SHARED_CORE ...
+$ ./configure --prefix=/path/to/install ...
 $ 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/modules\"
-$ make 
-$ cp src/libhttpd.so* /path/to/install/modules/
-$ cp src/libhttpd.ep  /path/to/install/modules/
-$ cp src/httpd        /path/to/install/bin/
-
        -
    2. Build and install a distributed Apache module, say @@ -252,27 +205,14 @@ $ cp src/httpd /path/to/install/bin/

        -
      • Build and install via configure (preferred): +
      • Build and install via configure: 
         $ ./configure --prefix=/path/to/install
-        --enable-shared=foo
+        --enable-foo=shared
 $ 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/modules
-- Edit /path/to/install/etc/httpd.conf
-  >> LoadModule foo_module /path/to/install/modules/mod_foo.so
-
        -
    3. Build and install a third-party Apache module, say @@ -280,27 +220,14 @@ $ cp src/xxxx/mod_foo.so /path/to/install/modules

        -
      • Build and install via configure (preferred): +
      • Build and install via configure: 
        -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c 
-        --enable-shared=foo
+$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c 
+        --enable-foo=shared
 $ 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/modules
-- Edit /path/to/install/etc/httpd.conf
-  >> LoadModule foo_module /path/to/install/modules/mod_foo.so
-
        -

      @@ -324,14 +251,14 @@ $ apxs -i -a -n foo mod_foo.so

      Advantages & Disadvantages

      -

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

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

      • The server package is more flexible at run-time because the actual server process can be assembled at run-time via LoadModule httpd.conf configuration commands instead of - Configuration AddModule commands at build-time. + configure options at build-time. For instance this way one is able to run different server instances (standard & SSL version, minimalistic & powered up version [mod_perl, PHP3], etc.) with only one Apache installation. @@ -372,20 +299,9 @@ $ apxs -i -a -n foo mod_foo.so and all other dynamic or static libraries used by the Apache core, or from static library archives (libfoo.a) containing position independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself via dlopen() or enabling the - SHARED_CHAIN rule while building Apache when your platform - supports linking DSO files against DSO libraries. + sure the Apache core itself already contains a reference to it or loading + the code yourself via dlopen().

        -

      • Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the SHARED_CORE feature because this - way the global symbols are forced to be exported. As a consequence the - Apache src/Configure script automatically enforces - SHARED_CORE on these platforms when DSO features are used in - the Configuration file or on the configure command line.