Commit 02f83c0f authored by pcs's avatar pcs
Browse files

Update docs to reflect the fact that mod_dll has been replaced by mod_so. 

In particular, mark mod_dll as obselete, add Windows information and
examples to mod_so documentation, copy info about creating DLLs from
mod_dll.html to mod_so.html (although this needs more work to add info
for Unix users, since most of the description applies to all systems).


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80623 13f79535-47bb-0310-9956-ffa450edef68
parent fbf98e52

docs/manual/mod/directives.html

+2 −4
Changes for docs/manual/mod/directives.html: 2 added lines, 4 removed lines.
Original line number Diff line number Diff line
@@ -120,10 +120,8 @@ of the terms used in their descriptions available. 
<LI><A HREF="core.html#limit">&lt;Limit&gt;</A>

<LI><A HREF="core.html#listen">Listen</A>

<LI><A HREF="core.html#listenbacklog">ListenBacklog</A>

<LI><A HREF="mod_so.html#loadfile">LoadFile</A> (Unix)

<LI><A HREF="mod_dll.html#loadfile">LoadFile</A> (Windows)

<LI><A HREF="mod_so.html#loadmodule">LoadModule</A> (Unix)

<LI><A HREF="mod_dll.html#loadmodule">LoadModule</A> (Windows)

<LI><A HREF="mod_so.html#loadfile">LoadFile</A>

<LI><A HREF="mod_so.html#loadmodule">LoadModule</A>

<LI><A HREF="core.html#location">&lt;Location&gt;</A>

<LI><A HREF="core.html#locationmatch">&lt;LocationMatch&gt;</A>

<LI><A HREF="core.html#lockfile">LockFile</A>

docs/manual/mod/index.html

+3 −3
Changes for docs/manual/mod/index.html: 3 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -60,8 +60,8 @@ mod_usertrack 
<DD>Basic directory handling.

<DT><A HREF="mod_dld.html">mod_dld</A> Apache 1.2.* and earlier

<DD>Start-time linking with the GNU libdld. Replaced in Apache 1.3 by mod_so

<DT><A HREF="mod_dll.html">mod_dll</A>

<DD>Start-time module linking with Win32 DLLs.

<DT><A HREF="mod_dll.html">mod_dll</A> Apache 1.3b1 to 1.3b5 only

<DD>Replaced in 1.3b6 by mod_so

<DT><A HREF="mod_env.html">mod_env</A>

<DD>Passing of environments to CGI scripts

<DT><A HREF="mod_example.html">mod_example</A> Apache 1.2 and up
@@ -100,7 +100,7 @@ mod_log_config module in Apache 1.2 and up 
<DT><A HREF="mod_setenvif.html">mod_setenvif</A> Apache 1.3 and up

<DD>Set environment variables based on client information

<DT><A HREF="mod_so.html">mod_so</A> Apache 1.3 and up

<DD>Experimental support for loading modules at runtime on Unix

<DD>Experimental support for loading modules (DLLs on Windows) at runtime

<DT><A HREF="mod_speling.html">mod_speling</A> Apache 1.3 and up

<DD>Automatically correct minor typos in URLs

<DT><A HREF="mod_status.html">mod_status</A>

docs/manual/mod/mod_so.html

+81 −11
Changes for docs/manual/mod/mod_so.html: 81 added lines, 11 removed lines.
Original line number Diff line number Diff line
@@ -15,11 +15,20 @@ 
<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Module mod_so</H1>



This module is contained in the <CODE>mod_so.c</CODE> file, and is not

compiled in by default. It provides for loading of executable code and

modules into the server at start-up time, on Unix systems. Win32

systems use <A HREF="mod_dll.html">mod_dll</A> instead. This module is

only available in Apache 1.3 and up.

This module is contained in the <CODE>mod_so.c</CODE> file. It is

compiled in by default on Windows and is not compiled in by default on

Unix. It provides for loading of executable code and modules into the

server at start-up or restart time. On Unix, the loaded code typically

comes from shared object files (usually with <SAMP>.so</SAMP>

extension), whilst on Windows this module loads <SAMP>DLL</SAMP>

files. This module is only available in Apache 1.3 and up.



<P>



In previous releases, the functionality of this module was provided

for Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll

was used in beta release 1.3b1 through 1.3b5. mod_so combines these

two modules into a single module for all operating systems.



<H2>Summary</H2>
@@ -55,10 +64,11 @@ a recompilation. 
 REL="Help"

><STRONG>Module:</STRONG></A> mod_so<P>



The LoadFile directive links in the named object files or libraries when

the server is started; this is used to load additional code which

may be required for some module to work. <EM>Filename</EM> is relative

to <A HREF="core.html#serverroot">ServerRoot</A>.<P><HR>

The LoadFile directive links in the named object files or libraries

when the server is started or restarted; this is used to load

additional code which may be required for some module to

work. <EM>Filename</EM> is either and absolute path or relative to <A

HREF="core.html#serverroot">ServerRoot</A>.<P><HR>



<H2><A name="loadmodule">LoadModule</A></H2>

<!--%plaintext &lt;?INDEX {\tt LoadModule} directive&gt; -->
@@ -82,11 +92,71 @@ to <A HREF="core.html#serverroot">ServerRoot</A>.<P><HR> 
The LoadModule directive links in the object file or library <EM>filename</EM>

and adds the module structure named <EM>module</EM> to the list of active

modules. <EM>Module</EM> is the name of the external variable of type

<CODE>module</CODE> in the file. Example:

<CODE>module</CODE> in the file. Example (Unix):

<BLOCKQUOTE><CODE>

LoadModule status_module modules/mod_status.so

</CODE></BLOCKQUOTE>

loads the module in the modules subdirectory of the ServerRoot.<P>



<P>



Example (Windows):

<BLOCKQUOTE><CODE>

LoadModule status_module modules/ApacheModuleStatus.dll<BR>

</CODE></BLOCKQUOTE>



loads the named module from the modules subdirectory of the

ServerRoot.<P>



<HR>



<H2><A name="creating">Creating DLL Modules for Windows</A></H2>



<P>The Apache module API is unchanged between the Unix and Windows

   versions. Many modules will run on Windows with no or little change

   from Unix, although others rely on aspects of the Unix architecture

   which are not present in Windows, and will not work.</P>



<P>When a module does work, it can be added to the server in one of two

   ways. As with Unix, it can be compiled into the server. Because Apache

   for Windows does not have the <CODE>Configure</CODE> program of Apache

   for Unix, the module's source file must be added to the ApacheCore

   project file, and its symbols must be added to the

   <CODE>os\win32\modules.c</CODE> file.</P>



<P>The second way is to compile the module as a DLL, a shared library

   that can be loaded into the server at runtime, using the

   <CODE><A HREF="#loadmodule">LoadModule</A></CODE>

   directive. These module DLLs can be distributed and run on any Apache

   for Windows installation, without recompilation of the server.</P>



<P>To create a module DLL, a small change is necessary to the module's

   source file: The module record must be exported from the DLL (which

   will be created later; see below). To do this, add the

   <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to

   your module's module record definition. For example, if your module

   has:</P>

<PRE>

    module foo_module;

</PRE>

<P>Replace the above with:</P>

<PRE>

    module MODULE_VAR_EXPORT foo_module;

</PRE>

<P>Note that this will only be activated on Windows, so the module can

   continue to be used, unchanged, with Unix if needed. Also, if you are

   familiar with <CODE>.DEF</CODE> files, you can export the module

   record with that method instead.</P>



<P>Now, create a DLL containing your module. You will need to link this

   against the ApacheCore.lib export library that is created when the

   ApacheCore.dll shared library is compiled. You may also have to change

   the compiler settings to ensure that the Apache header files are

   correctly located.</P>



<P>This should create a DLL version of your module. Now simply place it

   in the <SAMP>modules</SAMP> directory of your server root, and use

   the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to

   load it.</P>





<!--#include virtual="footer.html" -->