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

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.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 <manualpage metafile="apxs.xml.meta">
  24 <parentdocument href="./">Programs</parentdocument>
  25
  26 <title>apxs - APache eXtenSion tool</title>
  27
  28 <summary>
  29     <p><code>apxs</code> is a tool for building and installing extension
  30     modules for the Apache HyperText Transfer Protocol (HTTP) server. This is
  31     achieved by building a dynamic shared object (DSO) from one or more source
  32     or object <var>files</var> which then can be loaded into the Apache server
  33     under runtime via the <directive module="mod_so">LoadModule</directive>
  34     directive from <module>mod_so</module>.</p>
  35
  36     <p>So to use this extension mechanism your platform has to support the DSO
  37     feature and your Apache <program>httpd</program> binary has to be built with the
  38     <module>mod_so</module> module. The <code>apxs</code> tool automatically
  39     complains if this is not the case. You can check this yourself by manually
  40     running the command</p>
  41
  42     <example>
  43       $ httpd -l
  44     </example>
  45
  46     <p>The module <module>mod_so</module> should be part of the displayed list.
  47     If these requirements are fulfilled you can easily extend your Apache
  48     server's functionality by installing your own modules with the DSO mechanism
  49     by the help of this <code>apxs</code> tool:</p>
  50
  51     <example>
  52       $ apxs -i -a -c mod_foo.c<br />
  53       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
  54       ld -Bshareable -o mod_foo.so mod_foo.o<br />
  55       cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
  56       chmod 755 /path/to/apache/modules/mod_foo.so<br />
  57       [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
  58       $ apachectl restart<br />
  59       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
  60       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
  61       /path/to/apache/sbin/apachectl restart: httpd started<br />
  62       $ _
  63     </example>
  64
  65     <p>The arguments <var>files</var> can be any C source file (.c), a object
  66     file (.o) or even a library archive (.a). The <code>apxs</code> tool
  67     automatically recognizes these extensions and  automatically used the C
  68     source files for compilation while just using the object and archive files
  69     for the linking phase. But when using such pre-compiled objects make sure
  70     they are compiled for position independent code (PIC) to be able to use them
  71     for a dynamically loaded shared object. For instance with GCC you always
  72     just have to use <code>-fpic</code>. For other C compilers consult its
  73     manual page or at watch for the flags <code>apxs</code> uses to compile the
  74     object files.</p>
  75
  76     <p>For more details about DSO support in Apache read the documentation of
  77     <module>mod_so</module> or perhaps even read the
  78     <code>src/modules/standard/mod_so.c</code> source file.</p>
  79 </summary>
  80 <seealso><program>apachectl</program></seealso>
  81 <seealso><program>httpd</program></seealso>
  82
  83 <section id="synopsis"><title>Synopsis</title>
  84     <p><code><strong>apxs</strong> -<strong>g</strong>
  85     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  86     -<strong>n</strong> <var>modname</var></code></p>
  87
  88     <p><code><strong>apxs</strong> -<strong>q</strong>
  89     [ -<strong>v</strong> ]
  90     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  91     <var>query</var> ...</code></p>
  92
  93     <p><code><strong>apxs</strong> -<strong>c</strong>
  94     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
  95     [ -<strong>o</strong> <var>dsofile</var> ]
  96     [ -<strong>I</strong> <var>incdir</var> ]
  97     [ -<strong>D</strong> <var>name</var>=<var>value</var> ]
  98     [ -<strong>L</strong> <var>libdir</var> ]
  99     [ -<strong>l</strong> <var>libname</var> ]
 100     [ -<strong>Wc,</strong><var>compiler-flags</var> ]
 101     [ -<strong>Wl,</strong><var>linker-flags</var> ]
 102     <var>files</var> ...</code></p>
 103
 104     <p><code><strong>apxs</strong> -<strong>i</strong>
 105     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
 106     [ -<strong>n</strong> <var>modname</var> ]
 107     [ -<strong>a</strong> ]
 108     [ -<strong>A</strong> ]
 109     <var>dso-file</var> ...</code></p>
 110
 111     <p><code><strong>apxs</strong> -<strong>e</strong>
 112     [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
 113     [ -<strong>n</strong> <var>modname</var> ]
 114     [ -<strong>a</strong> ]
 115     [ -<strong>A</strong> ]
 116     <var>dso-file</var> ...</code></p>
 117 </section>
 118
 119 <section id="options"><title>Options</title>
 120     <section id="options.common"><title>Common Options</title>
 121       <dl>
 122       <dt><code>-n <var>modname</var></code></dt>
 123       <dd>This explicitly sets the module name for the <code>-i</code> (install)
 124       and <code>-g</code> (template generation) option. Use this to explicitly
 125       specify the module name. For option <code>-g</code> this is required, for
 126       option <code>-i</code> the <code>apxs</code> tool tries to determine the
 127       name from the source or (as a fallback) at least by guessing it from the
 128       filename.</dd>
 129       </dl>
 130     </section>
 131
 132     <section id="options.query"><title>Query Options</title>
 133       <dl>
 134       <dt><code>-q</code></dt>
 135       <dd>Performs a query for variables and environment settings used to
 136       build <code>httpd</code>.  When invoked without <var>query</var> parameters,
 137       it prints all known variables and their values.  The optional <code>-v</code>
 138       parameter formats the list output.
 139
 140       <p>Use this to manually determine settings used to build the
 141       <code>httpd</code> that will load your module.  For instance use</p>
 142       <example>
 143         INC=-I`apxs -q INCLUDEDIR`
 144       </example>
 145
 146       <p>inside your own Makefiles if you need manual access to Apache's C
 147       header files.</p></dd>
 148       </dl>
 149     </section>
 150
 151     <section id="options.conf"><title>Configuration Options</title>
 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     </section>
 157
 158     <section id="options.template"><title>Template Generation Options</title>
 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     </section>
 169
 170     <section id="options.dso"><title>DSO Compilation Options</title>
 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
 214       <dt><code>-p</code></dt>
 215       <dd>This option causes apxs to link against the apr/apr-util libraries.
 216       This is useful when compiling helper programs that use the apr/apr-util
 217       libraries.</dd>
 218       </dl>
 219     </section>
 220
 221     <section id="options.dsoinstall">
 222     <title>DSO Installation and Configuration Options</title>
 223       <dl>
 224       <dt><code>-i</code></dt>
 225       <dd>This indicates the installation operation and installs one or more
 226       dynamically shared objects into the server's <var>modules</var>
 227       directory.</dd>
 228
 229       <dt><code>-a</code></dt>
 230       <dd>This activates the module by automatically adding a corresponding
 231       <directive module="mod_so">LoadModule</directive> line to Apache's
 232       <code>httpd.conf</code> configuration file, or by enabling it if it
 233       already exists.</dd>
 234
 235       <dt><code>-A</code></dt>
 236       <dd>Same as option <code>-a</code> but the created <directive
 237       module="mod_so">LoadModule</directive> directive is prefixed with a hash
 238       sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for
 239       later activation but initially disabled.</dd>
 240
 241       <dt><code>-e</code></dt>
 242       <dd>This indicates the editing operation, which can be used with the
 243       <code>-a</code> and <code>-A</code> options similarly to the
 244       <code>-i</code> operation to edit Apache's <code>httpd.conf</code>
 245       configuration file without attempting to install the module.</dd>
 246       </dl>
 247     </section>
 248 </section>
 249
 250 <section id="examples"><title>Examples</title>
 251     <p>Assume you have an Apache module named <code>mod_foo.c</code> available
 252     which should extend Apache's server functionality. To accomplish this you
 253     first have to compile the C source into a shared object suitable for loading
 254     into the Apache server under runtime via the following command:</p>
 255
 256     <example>
 257       $ apxs -c mod_foo.c<br />
 258       /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br />
 259       /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br />
 260       $ _
 261     </example>
 262
 263     <p>Then you have to update the Apache configuration by making sure a
 264     <directive module="mod_so">LoadModule</directive> directive is present to
 265     load this shared object. To simplify this step <code>apxs</code> provides
 266     an automatic way to install the shared object in its "modules" directory
 267     and updating the <code>httpd.conf</code> file accordingly. This can be
 268     achieved by running:</p>
 269
 270     <example>
 271       $ apxs -i -a mod_foo.la<br />
 272       /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br />
 273       /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules
 274       ...
 275       chmod 755 /path/to/apache/modules/mod_foo.so<br />
 276       [activating module `foo' in /path/to/apache/conf/httpd.conf]<br />
 277       $ _
 278     </example>
 279
 280     <p>This way a line named</p>
 281
 282     <example>
 283       LoadModule foo_module modules/mod_foo.so
 284     </example>
 285
 286     <p>is added to the configuration file if still not present. If you want to
 287     have this disabled per default use the <code>-A</code> option,
 288     <em>i.e.</em></p>
 289
 290     <example>
 291       $ apxs -i -A mod_foo.c
 292     </example>
 293
 294     <p>For a quick test of the apxs mechanism you can create a sample Apache
 295     module template plus a corresponding Makefile via:</p>
 296
 297     <example>
 298       $ apxs -g -n foo<br />
 299       Creating [DIR]  foo<br />
 300       Creating [FILE] foo/Makefile<br />
 301       Creating [FILE] foo/modules.mk<br />
 302       Creating [FILE] foo/mod_foo.c<br />
 303       Creating [FILE] foo/.deps<br />
 304       $ _
 305     </example>
 306
 307     <p>Then you can immediately compile this sample module into a shared object
 308     and load it into the Apache server:</p>
 309
 310     <example>
 311       $ cd foo<br />
 312       $ make all reload<br />
 313       apxs -c mod_foo.c<br />
 314       /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br />
 315       /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br />
 316       apxs -i -a -n "foo" mod_foo.la<br />
 317       /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br />
 318       /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules
 319       ...
 320       chmod 755 /path/to/apache/modules/mod_foo.so<br />
 321       [activating module `foo' in /path/to/apache/conf/httpd.conf]<br />
 322       apachectl restart<br />
 323       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
 324       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
 325       /path/to/apache/sbin/apachectl restart: httpd started<br />
 326       $ _
 327     </example>
 328
 329 </section>
 330 </manualpage>