granicus.if.org Git - apache/blob - docs/manual/mod/mod_so.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_so.xml.meta">
  24
  25 <name>mod_so</name>
  26 <description>Loading of executable code and
  27 modules into the server at start-up or restart time</description>
  28 <status>Extension</status>
  29 <sourcefile>mod_so.c</sourcefile>
  30 <identifier>so_module</identifier>
  31 <compatibility>This is a Base module (always included) on
  32 Windows</compatibility>
  33
  34 <summary>
  35
  36     <p>On selected operating systems this module can be used to
  37     load modules into Apache HTTP Server at runtime via the <a
  38     href="../dso.html">Dynamic Shared Object</a> (DSO) mechanism,
  39     rather than requiring a recompilation.</p>
  40
  41     <p>On Unix, the loaded code typically comes from shared object
  42     files (usually with <code>.so</code> extension), on Windows
  43     this may either the <code>.so</code> or <code>.dll</code>
  44     extension.</p>
  45
  46     <note type="warning"><title>Warning</title>
  47     <p>Modules built for one major version of the Apache HTTP Server
  48     will generally not work on another. (e.g. 1.3 vs. 2.0, or 2.0 vs.
  49     2.2) There are usually API changes between one major version and
  50     another that require that modules be modified to work with the new
  51     version.</p>
  52     </note>
  53 </summary>
  54
  55 <section id="windows"><title>Creating Loadable Modules for Windows</title>
  56
  57     <note><title>Note</title>
  58     <p>On Windows, where loadable files typically have a file extension
  59     of <code>.dll</code>, Apache httpd modules are called
  60     <code>mod_whatever.so</code>, just as they are on other platforms.
  61     However, you may encounter third-party modules, such as PHP for
  62     example, that continue to use the <code>.dll</code> convention.</p>
  63
  64     <p>While <code>mod_so</code> still loads modules with
  65     <code>ApacheModuleFoo.dll</code> names, the new naming convention is
  66     preferred; if you are converting your loadable module for 2.0,
  67     please fix the name to this 2.0 convention.</p></note>
  68
  69     <p>The Apache httpd module API is unchanged between the Unix and
  70     Windows versions. Many modules will run on Windows with no or
  71     little change from Unix, although others rely on aspects of the
  72     Unix architecture which are not present in Windows, and will
  73     not work.</p>
  74
  75     <p>When a module does work, it can be added to the server in
  76     one of two ways. As with Unix, it can be compiled into the
  77     server. Because Apache httpd for Windows does not have the
  78     <code>Configure</code> program of Apache httpd for Unix, the module's
  79     source file must be added to the ApacheCore project file, and
  80     its symbols must be added to the
  81     <code>os\win32\modules.c</code> file.</p>
  82
  83     <p>The second way is to compile the module as a DLL, a shared
  84     library that can be loaded into the server at runtime, using
  85     the <code><directive>LoadModule</directive></code>
  86     directive. These module DLLs can be distributed and run on any
  87     Apache httpd for Windows installation, without recompilation of the
  88     server.</p>
  89
  90     <p>To create a module DLL, a small change is necessary to the
  91     module's source file: The module record must be exported from
  92     the DLL (which will be created later; see below). To do this,
  93     add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the
  94     Apache httpd header files) to your module's module record definition.
  95     For example, if your module has:</p>
  96
  97 <example>
  98     module foo_module;
  99 </example>
 100
 101     <p>Replace the above with:</p>
 102 <example>
 103     module AP_MODULE_DECLARE_DATA foo_module;
 104 </example>
 105
 106     <p>Note that this will only be activated on Windows, so the
 107     module can continue to be used, unchanged, with Unix if needed.
 108     Also, if you are familiar with <code>.DEF</code> files, you can
 109     export the module record with that method instead.</p>
 110
 111     <p>Now, create a DLL containing your module. You will need to
 112     link this against the libhttpd.lib export library that is
 113     created when the libhttpd.dll shared library is compiled. You
 114     may also have to change the compiler settings to ensure that
 115     the Apache httpd header files are correctly located. You can find
 116     this library in your server root's modules directory. It is
 117     best to grab an existing module .dsp file from the tree to
 118     assure the build environment is configured correctly, or
 119     alternately compare the compiler and link options to your
 120     .dsp.</p>
 121
 122     <p>This should create a DLL version of your module. Now simply
 123     place it in the <code>modules</code> directory of your server
 124     root, and use the <directive>LoadModule</directive>
 125     directive to load it.</p>
 126
 127 </section>
 128
 129 <directivesynopsis>
 130 <name>LoadFile</name>
 131 <description>Link in the named object file or library</description>
 132 <syntax>LoadFile <em>filename</em> [<em>filename</em>] ...</syntax>
 133 <contextlist>
 134 <context>server config</context>
 135 <context>virtual host</context>
 136 </contextlist>
 137
 138 <usage>
 139
 140     <p>The LoadFile directive links in the named object files or
 141     libraries when the server is started or restarted; this is used
 142     to load additional code which may be required for some module
 143     to work. <em>Filename</em> is either an absolute path or
 144     relative to <a href="core.html#serverroot">ServerRoot</a>.</p>
 145
 146     <p>For example:</p>
 147
 148     <highlight language="config">LoadFile libexec/libxmlparse.so</highlight>
 149
 150 </usage>
 151 </directivesynopsis>
 152
 153 <directivesynopsis>
 154 <name>LoadModule</name>
 155 <description>Links in the object file or library, and adds to the list
 156 of active modules</description>
 157 <syntax>LoadModule <em>module filename</em></syntax>
 158 <contextlist>
 159 <context>server config</context>
 160 <context>virtual host</context>
 161 </contextlist>
 162
 163 <usage>
 164     <p>The LoadModule directive links in the object file or library
 165     <em>filename</em> and adds the module structure named
 166     <em>module</em> to the list of active modules. <em>Module</em>
 167     is the name of the external variable of type
 168     <code>module</code> in the file, and is listed as the <a
 169     href="module-dict.html#ModuleIdentifier">Module Identifier</a>
 170     in the module documentation. Example:</p>
 171
 172     <highlight language="config">
 173       LoadModule status_module modules/mod_status.so
 174     </highlight>
 175
 176     <p>loads the named module from the modules subdirectory of the
 177     ServerRoot.</p>
 178 </usage>
 179
 180 </directivesynopsis>
 181 </modulesynopsis>
 182