diff options
| author | Ryan Bloom <rbb@apache.org> | 2001-09-03 16:31:27 +0000 |
|---|---|---|
| committer | Ryan Bloom <rbb@apache.org> | 2001-09-03 16:31:27 +0000 |
| commit | 9f4a4c0ed9345ebb550e8d2ba85335a70f10b2df (patch) | |
| tree | 3627ff231af671bce057b378e387b95951112d9b /docs/manual/dso.html | |
| parent | d3c7404f6b0da8836a8bb3ef0a802538d91ee9b4 (diff) | |
| download | httpd-9f4a4c0ed9345ebb550e8d2ba85335a70f10b2df.tar.gz | |
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
Diffstat (limited to 'docs/manual/dso.html')
| -rw-r--r-- | docs/manual/dso.html | 118 |
1 files changed, 17 insertions, 101 deletions
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 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML><HEAD> -<TITLE>Apache 1.3 Dynamic Shared Object (DSO) support</TITLE> +<TITLE>Apache 2.0 Dynamic Shared Object (DSO) support</TITLE> </HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> @@ -17,7 +17,7 @@ <DIV ALIGN=CENTER> <H1> -Apache 1.3<BR> +Apache 2.0<BR> Dynamic Shared Object (DSO)<BR> Support </H1> @@ -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. -<P>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. - <H3>Implementation</H3> <P>The DSO support for loading individual Apache modules is based on a module named <A HREF="mod/mod_so.html"><CODE>mod_so.c</CODE></A> which has to be statically compiled into the Apache core. It is the only module besides -<CODE>http_core.c</CODE> which cannot be put into a DSO itself +<CODE>core.c</CODE> 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 -<CODE>configure</CODE>'s <CODE>--enable-shared</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>AddModule</CODE> command -in your <CODE>src/Configuration</CODE> into a <CODE>SharedModule</CODE> -command (see <CODE>src/INSTALL</CODE> file). After a module is compiled into +<CODE>configure</CODE>'s <CODE>--enable-<i>module</i>=shared</CODE> option +(see top-level <CODE>INSTALL</CODE> file). After a module is compiled into a DSO named <CODE>mod_foo.so</CODE> you can use <A HREF="mod/mod_so.html"><CODE>mod_so</CODE></A>'s <A HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> command in your @@ -145,23 +138,6 @@ into the <CODE>apxs</CODE> 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. -<P>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 -<CODE>SHARED_CORE</CODE> has to be enabled via <CODE>configure</CODE>'s -<CODE>--enable-rule=SHARED_CORE</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>Rule</CODE> command in -your <CODE>Configuration</CODE> file to <CODE>Rule SHARED_CORE=yes</CODE> (see -<CODE>src/INSTALL</CODE> file). The Apache core code is then placed into a DSO -library named <CODE>libhttpd.so</CODE>. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -<CODE>libhttpd.ep</CODE> is created which both binds this static code and -provides a stub for the <CODE>main()</CODE> function. Finally the -<CODE>httpd</CODE> executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -<CODE>libhttpd.ep</CODE> by providing the <CODE>LD_LIBRARY_PATH</CODE> to -<CODE>libhttpd.so</CODE>. - <H3>Supported Platforms</H3> <P>Apache's <CODE>src/Configure</CODE> script currently has only limited but @@ -208,43 +184,20 @@ o Ultrix (no dlopen-style interface under this platform) <H3>Usage Summary</H3> -<P>To give you an overview of the DSO features of Apache 1.3, here is a short +<P>To give you an overview of the DSO features of Apache 2.0, here is a short and concise summary: <OL> -<LI>Placing the Apache core code (all the stuff which usually forms the -<CODE>httpd</CODE> binary) into a DSO <CODE>libhttpd.so</CODE>, an executable -program <CODE>libhttpd.ep</CODE> and a bootstrapping executable program -<CODE>httpd</CODE> (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): - <P> <UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): +<LI>Build and install via <CODE>configure</CODE>: <TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> <PRE> -$ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... +$ ./configure --prefix=/path/to/install ... $ make install </PRE> </TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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/ -</PRE> -</TD></TR></TABLE> </UL> <LI>Build and install a <EM>distributed</EM> Apache module, say @@ -252,27 +205,14 @@ $ cp src/httpd /path/to/install/bin/ <P> <UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): +<LI>Build and install via <CODE>configure</CODE>: <TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> <PRE> $ ./configure --prefix=/path/to/install - --enable-shared=foo + --enable-foo=shared $ make install </PRE> </TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- 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 -</PRE> -</TD></TR></TABLE> </UL> <LI>Build and install a <EM>third-party</EM> Apache module, say @@ -280,27 +220,14 @@ $ cp src/xxxx/mod_foo.so /path/to/install/modules <P> <UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): +<LI>Build and install via <CODE>configure</CODE>: <TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> <PRE> -$ ./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 </PRE> </TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ 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 -</PRE> -</TD></TR></TABLE> </UL> <P> @@ -324,14 +251,14 @@ $ apxs -i -a -n foo mod_foo.so <H3>Advantages & Disadvantages</H3> -<P>The above DSO based features of Apache 1.3 have the following advantages: +<P>The above DSO based features of Apache 2.0 have the following advantages: <UL> <LI> The server package is more flexible at run-time because the actual server process can be assembled at run-time via <A HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> <CODE>httpd.conf</CODE> configuration commands instead of - <CODE>Configuration</CODE> <CODE>AddModule</CODE> commands at build-time. + <CODE>configure</CODE> 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], <EM>etc.</EM>) 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 (<CODE>libfoo.a</CODE>) 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 <CODE>dlopen()</CODE> or enabling the - <CODE>SHARED_CHAIN</CODE> 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 <CODE>dlopen()</CODE>. <P> -<LI> 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 <CODE>SHARED_CORE</CODE> feature because this - way the global symbols are forced to be exported. As a consequence the - Apache <CODE>src/Configure</CODE> script automatically enforces - <CODE>SHARED_CORE</CODE> on these platforms when DSO features are used in - the <CODE>Configuration</CODE> file or on the configure command line. </UL> <!--#include virtual="footer.html" --> |