svn commit: r927382 - /httpd/httpd/trunk/docs/manual/dso.xml

[rb...@apache.org]

Author: rbowen
Date: Thu Mar 25 13:20:39 2010
New Revision: 927382

URL: http://svn.apache.org/viewvc?rev=927382&view=rev
Log:
Bring this doc a little further into this century. Considering dropping,
or at least rewriting, most of the "Background" section.

Modified:
    httpd/httpd/trunk/docs/manual/dso.xml

Modified: httpd/httpd/trunk/docs/manual/dso.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/dso.xml?rev=927382&r1=927381&r2=927382&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/dso.xml (original)
+++ httpd/httpd/trunk/docs/manual/dso.xml Thu Mar 25 13:20:39 2010
@@ -59,7 +59,7 @@
     itself. Practically all other distributed Apache httpd modules can then
     be placed into a DSO by individually enabling the DSO build for
     them via <program>configure</program>'s
-    <code>--enable-<em>module</em>=shared</code> option as discussed
+    <code>--enable-mods-shared</code> option as discussed
     in the <a href="install.html">install documentation</a>. After a
     module is compiled into a DSO named <code>mod_foo.so</code> you
     can use <module>mod_so</module>'s <directive
@@ -68,7 +68,7 @@
     or restart.</p>
 
     <p>To simplify this creation of DSO files for Apache httpd modules
-    (especially for third-party modules) a new support program
+    (especially for third-party modules) a support program
     named <program>apxs</program> (<dfn>APache
     eXtenSion</dfn>) is available. It can be used to build DSO based
     modules <em>outside of</em> the Apache httpd source tree. The idea is
@@ -90,38 +90,41 @@
 
     <ol>
       <li>
-        Build and install a <em>distributed</em> Apache httpd module, say
+        <p>Build and install a <em>distributed</em> Apache httpd module, say
         <code>mod_foo.c</code>, into its own DSO
-        <code>mod_foo.so</code>: 
+        <code>mod_foo.so</code>:</p>
 
 <example>
-$ ./configure --prefix=/path/to/install --enable-foo=shared<br />
+$ ./configure --prefix=/path/to/install --enable-foo --enable-mods-shared=foo<br />
 $ make install
 </example>
       </li>
 
       <li>
-        Build and install a <em>third-party</em> Apache httpd module, say
-        <code>mod_foo.c</code>, into its own DSO
-        <code>mod_foo.so</code>: 
+        <p>Configure Apache HTTP Server for <em>later installation</em> of shared
+        modules:</p>
 
 <example>
-$ ./configure --add-module=<var>module_type</var>:/path/to/3rdparty/mod_foo.c \<br />
-<indent>
-  --enable-foo=shared<br />
-</indent>
+$ ./configure --enable-so<br />
 $ make install
 </example>
       </li>
 
       <li>
-        Configure Apache HTTP Server for <em>later installation</em> of shared
-        modules: 
+      <p>Configure Apache HTTP Server with all modules enabled, and loaded
+      as shared objects. You can then remove individual ones by
+      commenting out the <directive
+      module="mod_so">LoadModule</directive> directives in
+      <code>httpd.conf</code>.</p>
 
 <example>
-$ ./configure --enable-so<br />
+$ ./configure --enable-modules=most --enable-mods-shared=all<br />
 $ make install
 </example>
+   
+        <p>The <code>most</code> argument to
+        <code>--enable-modules</code> indicates that all modules
+        which are not experimental or example modules will be built.</p>
       </li>
 
       <li>
@@ -132,8 +135,7 @@ $ make install
 
 <example>
 $ cd /path/to/3rdparty<br />
-$ apxs -c mod_foo.c<br />
-$ apxs -i -a -n foo mod_foo.la
+$ apxs -cia mod_foo.c
 </example>
       </li>
     </ol>
@@ -142,6 +144,8 @@ $ apxs -i -a -n foo mod_foo.la
     use a <directive module="mod_so">LoadModule</directive>
     directive in <code>httpd.conf</code> to tell Apache httpd to activate
     the module.</p>
+
+    <p>See the <a href="programs/apxs.html">apxs documentation</a> for more details.</p>
 </section>
 
 <section id="background"><title>Background</title>
@@ -234,16 +238,6 @@ $ apxs -i -a -n foo mod_foo.la
     provides. On the other hand using shared objects for extending
     a program is not used by a lot of programs.</p>
 
-    <p>As of 1998 there were only a few software packages available
-    which use the DSO mechanism to extend their
-    functionality at run-time: Perl 5 (via its XS mechanism and the
-    DynaLoader module), Netscape Server, <em>etc.</em> Starting
-    with version 1.3, Apache HTTP Server joined the crew, because Apache httpd
-    already uses a module concept to extend its functionality and
-    internally uses a dispatch-list-based approach to link external
-    modules into the Apache httpd core functionality. So, Apache httpd is
-    really predestined for using DSO to load its modules at
-    run-time.</p>
 </section>
 
 <section id="advantages"><title>Advantages and Disadvantages</title>
@@ -266,7 +260,7 @@ $ apxs -i -a -n foo mod_foo.la
       third-party modules even after installation. This is at least
       a great benefit for vendor package maintainers who can create
       a Apache httpd core package and additional packages containing
-      extensions like PHP3, mod_perl, mod_fastcgi,
+      extensions like PHP, mod_perl, mod_security,
       <em>etc.</em></li>
 
       <li>Easier Apache httpd module prototyping because with the