granicus.if.org Git - apache/blob - docs/manual/programs/apxs.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>apxs - APache eXtenSion tool - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.1</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Programs</a></div><div id="page-content"><div id="preamble"><h1>apxs - APache eXtenSion tool</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/programs/apxs.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="../ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  23 </div>
  24
  25     <p><code>apxs</code> is a tool for building and installing extension
  26     modules for the Apache HyperText Transfer Protocol (HTTP) server. This is
  27     achieved by building a dynamic shared object (DSO) from one or more source
  28     or object <var>files</var> which then can be loaded into the Apache server
  29     under runtime via the <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>
  30     directive from <code class="module"><a href="../mod/mod_so.html">mod_so</a></code>.</p>
  31
  32     <p>So to use this extension mechanism your platform has to support the DSO
  33     feature and your Apache <code class="program"><a href="../programs/httpd.html">httpd</a></code> binary has to be built with the
  34     <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> module. The <code>apxs</code> tool automatically
  35     complains if this is not the case. You can check this yourself by manually
  36     running the command</p>
  37
  38     <div class="example"><p><code>
  39       $ httpd -l
  40     </code></p></div>
  41
  42     <p>The module <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> should be part of the displayed list.
  43     If these requirements are fulfilled you can easily extend your Apache
  44     server's functionality by installing your own modules with the DSO mechanism
  45     by the help of this <code>apxs</code> tool:</p>
  46
  47     <div class="example"><p><code>
  48       $ apxs -i -a -c mod_foo.c<br />
  49       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
  50       ld -Bshareable -o mod_foo.so mod_foo.o<br />
  51       cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
  52       chmod 755 /path/to/apache/modules/mod_foo.so<br />
  53       [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
  54       $ apachectl restart<br />
  55       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
  56       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
  57       /path/to/apache/sbin/apachectl restart: httpd started<br />
  58       $ _
  59     </code></p></div>
  60
  61     <p>The arguments <var>files</var> can be any C source file (.c), a object
  62     file (.o) or even a library archive (.a). The <code>apxs</code> tool
  63     automatically recognizes these extensions and  automatically used the C
  64     source files for compilation while just using the object and archive files
  65     for the linking phase. But when using such pre-compiled objects make sure
  66     they are compiled for position independent code (PIC) to be able to use them
  67     for a dynamically loaded shared object. For instance with GCC you always
  68     just have to use <code>-fpic</code>. For other C compilers consult its
  69     manual page or at watch for the flags <code>apxs</code> uses to compile the
  70     object files.</p>
  71
  72     <p>For more details about DSO support in Apache read the documentation of
  73     <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> or perhaps even read the
  74     <code>src/modules/standard/mod_so.c</code> source file.</p>
  75 </div>
  76 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#synopsis">Synopsis</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  79 </ul><h3>See also</h3><ul class="seealso"><li><code class="program"><a href="../programs/apachectl.html">apachectl</a></code></li><li><code class="program"><a href="../programs/httpd.html">httpd</a></code></li></ul></div>
  80 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  81 <div class="section">
  82 <h2><a name="synopsis" id="synopsis">Synopsis</a></h2>
  83     <p><code><strong>apxs</strong> -<strong>g</strong>
  84     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  85     -<strong>n</strong> <var>modname</var></code></p>
  86
  87     <p><code><strong>apxs</strong> -<strong>q</strong>
  88     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  89     <var>query</var> ...</code></p>
  90
  91     <p><code><strong>apxs</strong> -<strong>c</strong>
  92     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  93     [ -<strong>o</strong> <var>dsofile</var> ]
  94     [ -<strong>I</strong> <var>incdir</var> ]
  95     [ -<strong>D</strong> <var>name</var>=<var>value</var> ]
  96     [ -<strong>L</strong> <var>libdir</var> ]
  97     [ -<strong>l</strong> <var>libname</var> ]
  98     [ -<strong>Wc,</strong><var>compiler-flags</var> ]
  99     [ -<strong>Wl,</strong><var>linker-flags</var> ]
 100     <var>files</var> ...</code></p>
 101
 102     <p><code><strong>apxs</strong> -<strong>i</strong>
 103     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
 104     [ -<strong>n</strong> <var>modname</var> ]
 105     [ -<strong>a</strong> ]
 106     [ -<strong>A</strong> ]
 107     <var>dso-file</var> ...</code></p>
 108
 109     <p><code><strong>apxs</strong> -<strong>e</strong>
 110     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
 111     [ -<strong>n</strong> <var>modname</var> ]
 112     [ -<strong>a</strong> ]
 113     [ -<strong>A</strong> ]
 114     <var>dso-file</var> ...</code></p>
 115 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 116 <div class="section">
 117 <h2><a name="options" id="options">Options</a></h2>
 118     <h3><a name="options.common" id="options.common">Common Options</a></h3>
 119       <dl>
 120       <dt><code>-n <var>modname</var></code></dt>
 121       <dd>This explicitly sets the module name for the <code>-i</code> (install)
 122       and <code>-g</code> (template generation) option. Use this to explicitly
 123       specify the module name. For option <code>-g</code> this is required, for
 124       option <code>-i</code> the <code>apxs</code> tool tries to determine the
 125       name from the source or (as a fallback) at least by guessing it from the
 126       filename.</dd>
 127       </dl>
 128
 129
 130     <h3><a name="options.query" id="options.query">Query Options</a></h3>
 131       <dl>
 132       <dt><code>-q</code></dt>
 133       <dd>Performs a query for <code>apxs</code>'s knowledge about certain
 134       settings. The <var>query</var> parameters can be one or more of the
 135       following strings: <code>CC</code>, <code>CFLAGS</code>,
 136       <code>CFLAGS_SHLIB</code>, <code>INCLUDEDIR</code>, <code>LD_SHLIB</code>,
 137       <code>LDFLAGS_SHLIB</code>, <code>LIBEXECDIR</code>,
 138       <code>LIBS_SHLIB</code>, <code>SBINDIR</code>, <code>SYSCONFDIR</code>,
 139       <code>TARGET</code>.
 140
 141       <p>Use this for manually determining settings. For instance use</p>
 142       <div class="example"><p><code>
 143         INC=-I`apxs -q INCLUDEDIR`
 144       </code></p></div>
 145
 146       <p>inside your own Makefiles if you need manual access to Apache's C
 147       header files.</p></dd>
 148       </dl>
 149
 150
 151     <h3><a name="options.conf" id="options.conf">Configuration Options</a></h3>
 152       <dl>
 153       <dt><code>-S <var>name</var>=<var>value</var></code></dt>
 154       <dd>This option changes the apxs settings described above.</dd>
 155       </dl>
 156
 157
 158     <h3><a name="options.template" id="options.template">Template Generation Options</a></h3>
 159       <dl>
 160       <dt><code>-g</code></dt>
 161       <dd>This generates a subdirectory <var>name</var> (see option
 162       <code>-n</code>) and there two files: A sample module source file named
 163       <code>mod_<var>name</var>.c</code> which can be used as a template for
 164       creating your own modules or as a quick start for playing with the
 165       apxs mechanism. And a corresponding <code>Makefile</code> for even easier
 166       build and installing of this module.</dd>
 167       </dl>
 168
 169
 170     <h3><a name="options.dso" id="options.dso">DSO Compilation Options</a></h3>
 171       <dl>
 172       <dt><code>-c</code></dt>
 173       <dd>This indicates the compilation operation. It first compiles the C
 174       source files (.c) of <var>files</var> into corresponding object files (.o)
 175       and then builds a dynamically shared object in <var>dsofile</var> by
 176       linking these object files plus the remaining object files (.o and .a) of
 177       <var>files</var>. If no <code>-o</code> option is specified the output
 178       file is guessed from the first filename in <var>files</var> and thus
 179       usually defaults to <code>mod_<var>name</var>.so</code>.</dd>
 180
 181       <dt><code>-o <var>dsofile</var></code></dt>
 182       <dd>Explicitly specifies the filename of the created dynamically shared
 183       object. If not specified and the name cannot be guessed from the
 184       <var>files</var> list, the fallback name <code>mod_unknown.so</code> is
 185       used.</dd>
 186
 187       <dt><code>-D <var>name</var>=<var>value</var></code></dt>
 188       <dd>This option is directly passed through to the compilation command(s).
 189       Use this to add your own defines to the build process.</dd>
 190
 191       <dt><code>-I <var>incdir</var></code></dt>
 192       <dd>This option is directly passed through to the compilation command(s).
 193       Use this to add your own include directories to search to the build
 194       process.</dd>
 195
 196       <dt><code>-L <var>libdir</var></code></dt>
 197       <dd>This option is directly passed through to the linker command. Use this
 198       to add your own library directories to search to the build  process.</dd>
 199
 200       <dt><code>-l <var>libname</var></code></dt>
 201       <dd>This option is directly passed through to the linker command. Use this
 202       to add your own libraries to search to the build process.</dd>
 203
 204       <dt><code>-Wc,<var>compiler-flags</var></code></dt>
 205       <dd>This option passes <var>compiler-flags</var> as additional flags to
 206       the <code>libtool --mode=compile</code> command. Use this to add local
 207       compiler-specific options.</dd>
 208
 209       <dt><code>-Wl,<var>linker-flags</var></code></dt>
 210       <dd>This option passes <var>linker-flags</var> as additional
 211       flags to the <code>libtool --mode=link</code> command. Use this
 212       to add local linker-specific options.</dd>
 213       </dl>
 214
 215
 216     <h3><a name="options.dsoinstall" id="options.dsoinstall">DSO Installation and Configuration Options</a></h3>
 217
 218       <dl>
 219       <dt><code>-i</code></dt>
 220       <dd>This indicates the installation operation and installs one or more
 221       dynamically shared objects into the server's <var>modules</var>
 222       directory.</dd>
 223
 224       <dt><code>-a</code></dt>
 225       <dd>This activates the module by automatically adding a corresponding
 226       <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> line to Apache's
 227       <code>httpd.conf</code> configuration file, or by enabling it if it
 228       already exists.</dd>
 229
 230       <dt><code>-A</code></dt>
 231       <dd>Same as option <code>-a</code> but the created <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive is prefixed with a hash
 232       sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for
 233       later activation but initially disabled.</dd>
 234
 235       <dt><code>-e</code></dt>
 236       <dd>This indicates the editing operation, which can be used with the
 237       <code>-a</code> and <code>-A</code> options similarly to the
 238       <code>-i</code> operation to edit Apache's <code>httpd.conf</code>
 239       configuration file without attempting to install the module.</dd>
 240       </dl>
 241
 242 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 243 <div class="section">
 244 <h2><a name="examples" id="examples">Examples</a></h2>
 245     <p>Assume you have an Apache module named <code>mod_foo.c</code> available
 246     which should extend Apache's server functionality. To accomplish this you
 247     first have to compile the C source into a shared object suitable for loading
 248     into the Apache server under runtime via the following command:</p>
 249
 250     <div class="example"><p><code>
 251       $ apxs -c mod_foo.c<br />
 252       /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br />
 253       /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br />
 254       $ _
 255     </code></p></div>
 256
 257     <p>Then you have to update the Apache configuration by making sure a
 258     <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive is present to
 259     load this shared object. To simplify this step <code>apxs</code> provides
 260     an automatic way to install the shared object in its "modules" directory
 261     and updating the <code>httpd.conf</code> file accordingly. This can be
 262     achieved by running:</p>
 263
 264     <div class="example"><p><code>
 265       $ apxs -i -a mod_foo.la<br />
 266       /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br />
 267       /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules
 268       ...
 269       chmod 755 /path/to/apache/modules/mod_foo.so<br />
 270       [activating module `foo' in /path/to/apache/conf/httpd.conf]<br />
 271       $ _
 272     </code></p></div>
 273
 274     <p>This way a line named</p>
 275
 276     <div class="example"><p><code>
 277       LoadModule foo_module modules/mod_foo.so
 278     </code></p></div>
 279
 280     <p>is added to the configuration file if still not present. If you want to
 281     have this disabled per default use the <code>-A</code> option,
 282     <em>i.e.</em></p>
 283
 284     <div class="example"><p><code>
 285       $ apxs -i -A mod_foo.c
 286     </code></p></div>
 287
 288     <p>For a quick test of the apxs mechanism you can create a sample Apache
 289     module template plus a corresponding Makefile via:</p>
 290
 291     <div class="example"><p><code>
 292       $ apxs -g -n foo<br />
 293       Creating [DIR]  foo<br />
 294       Creating [FILE] foo/Makefile<br />
 295       Creating [FILE] foo/modules.mk<br />
 296       Creating [FILE] foo/mod_foo.c<br />
 297       Creating [FILE] foo/.deps<br />
 298       $ _
 299     </code></p></div>
 300
 301     <p>Then you can immediately compile this sample module into a shared object
 302     and load it into the Apache server:</p>
 303
 304     <div class="example"><p><code>
 305       $ cd foo<br />
 306       $ make all reload<br />
 307       apxs -c mod_foo.c<br />
 308       /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br />
 309       /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br />
 310       apxs -i -a -n "foo" mod_foo.la<br />
 311       /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br />
 312       /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules
 313       ...
 314       chmod 755 /path/to/apache/modules/mod_foo.so<br />
 315       [activating module `foo' in /path/to/apache/conf/httpd.conf]<br />
 316       apachectl restart<br />
 317       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
 318       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
 319       /path/to/apache/sbin/apachectl restart: httpd started<br />
 320       $ _
 321     </code></p></div>
 322
 323 </div></div>
 324 <div class="bottomlang">
 325 <p><span>Available Languages: </span><a href="../en/programs/apxs.html" title="English">&nbsp;en&nbsp;</a> |
 326 <a href="../ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 327 </div><div id="footer">
 328 <p class="apache">Copyright 1999-2004 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 329 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 330 </body></html>