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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.2</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Programs</a></div><div id="page-content"><div id="preamble"><h1>apxs - APache eXtenSion tool</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/programs/apxs.html" title="English"> en </a> | 25<a href="/ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 26<a href="/tr/programs/apxs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 27</div> 28 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 <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> 34 directive from <code class="module"><a href="/mod/mod_so.html">mod_so</a></code>.</p> 35 36 <p>So to use this extension mechanism your platform has to support the DSO 37 feature and your Apache <code class="program"><a href="/programs/httpd.html">httpd</a></code> binary has to be built with the 38 <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> 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 <div class="example"><p><code> 43 $ httpd -l 44 </code></p></div> 45 46 <p>The module <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> 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 <div class="example"><p><code> 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 </code></p></div> 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 <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> or perhaps even read the 78 <code>src/modules/standard/mod_so.c</code> source file.</p> 79</div> 80<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#synopsis">Synopsis</a></li> 81<li><img alt="" src="/images/down.gif" /> <a href="#options">Options</a></li> 82<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li> 83</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><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 84<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 85<div class="section"> 86<h2><a name="synopsis" id="synopsis">Synopsis</a></h2> 87 <p><code><strong>apxs</strong> -<strong>g</strong> 88 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 89 -<strong>n</strong> <var>modname</var></code></p> 90 91 <p><code><strong>apxs</strong> -<strong>q</strong> 92 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 93 <var>query</var> ...</code></p> 94 95 <p><code><strong>apxs</strong> -<strong>c</strong> 96 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 97 [ -<strong>o</strong> <var>dsofile</var> ] 98 [ -<strong>I</strong> <var>incdir</var> ] 99 [ -<strong>D</strong> <var>name</var>=<var>value</var> ] 100 [ -<strong>L</strong> <var>libdir</var> ] 101 [ -<strong>l</strong> <var>libname</var> ] 102 [ -<strong>Wc,</strong><var>compiler-flags</var> ] 103 [ -<strong>Wl,</strong><var>linker-flags</var> ] 104 <var>files</var> ...</code></p> 105 106 <p><code><strong>apxs</strong> -<strong>i</strong> 107 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 108 [ -<strong>n</strong> <var>modname</var> ] 109 [ -<strong>a</strong> ] 110 [ -<strong>A</strong> ] 111 <var>dso-file</var> ...</code></p> 112 113 <p><code><strong>apxs</strong> -<strong>e</strong> 114 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 115 [ -<strong>n</strong> <var>modname</var> ] 116 [ -<strong>a</strong> ] 117 [ -<strong>A</strong> ] 118 <var>dso-file</var> ...</code></p> 119</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 120<div class="section"> 121<h2><a name="options" id="options">Options</a></h2> 122 <h3><a name="options.common" id="options.common">Common Options</a></h3> 123 <dl> 124 <dt><code>-n <var>modname</var></code></dt> 125 <dd>This explicitly sets the module name for the <code>-i</code> (install) 126 and <code>-g</code> (template generation) option. Use this to explicitly 127 specify the module name. For option <code>-g</code> this is required, for 128 option <code>-i</code> the <code>apxs</code> tool tries to determine the 129 name from the source or (as a fallback) at least by guessing it from the 130 filename.</dd> 131 </dl> 132 133 134 <h3><a name="options.query" id="options.query">Query Options</a></h3> 135 <dl> 136 <dt><code>-q</code></dt> 137 <dd>Performs a query for <code>apxs</code>'s knowledge about certain 138 settings. The <var>query</var> parameters can be one or more of the 139 following strings: <code>CC</code>, <code>CFLAGS</code>, 140 <code>CFLAGS_SHLIB</code>, <code>INCLUDEDIR</code>, <code>LD_SHLIB</code>, 141 <code>LDFLAGS_SHLIB</code>, <code>LIBEXECDIR</code>, 142 <code>LIBS_SHLIB</code>, <code>SBINDIR</code>, <code>SYSCONFDIR</code>, 143 <code>TARGET</code>. 144 145 <p>Use this for manually determining settings. For instance use</p> 146 <div class="example"><p><code> 147 INC=-I`apxs -q INCLUDEDIR` 148 </code></p></div> 149 150 <p>inside your own Makefiles if you need manual access to Apache's C 151 header files.</p></dd> 152 </dl> 153 154 155 <h3><a name="options.conf" id="options.conf">Configuration Options</a></h3> 156 <dl> 157 <dt><code>-S <var>name</var>=<var>value</var></code></dt> 158 <dd>This option changes the apxs settings described above.</dd> 159 </dl> 160 161 162 <h3><a name="options.template" id="options.template">Template Generation Options</a></h3> 163 <dl> 164 <dt><code>-g</code></dt> 165 <dd>This generates a subdirectory <var>name</var> (see option 166 <code>-n</code>) and there two files: A sample module source file named 167 <code>mod_<var>name</var>.c</code> which can be used as a template for 168 creating your own modules or as a quick start for playing with the 169 apxs mechanism. And a corresponding <code>Makefile</code> for even easier 170 build and installing of this module.</dd> 171 </dl> 172 173 174 <h3><a name="options.dso" id="options.dso">DSO Compilation Options</a></h3> 175 <dl> 176 <dt><code>-c</code></dt> 177 <dd>This indicates the compilation operation. It first compiles the C 178 source files (.c) of <var>files</var> into corresponding object files (.o) 179 and then builds a dynamically shared object in <var>dsofile</var> by 180 linking these object files plus the remaining object files (.o and .a) of 181 <var>files</var>. If no <code>-o</code> option is specified the output 182 file is guessed from the first filename in <var>files</var> and thus 183 usually defaults to <code>mod_<var>name</var>.so</code>.</dd> 184 185 <dt><code>-o <var>dsofile</var></code></dt> 186 <dd>Explicitly specifies the filename of the created dynamically shared 187 object. If not specified and the name cannot be guessed from the 188 <var>files</var> list, the fallback name <code>mod_unknown.so</code> is 189 used.</dd> 190 191 <dt><code>-D <var>name</var>=<var>value</var></code></dt> 192 <dd>This option is directly passed through to the compilation command(s). 193 Use this to add your own defines to the build process.</dd> 194 195 <dt><code>-I <var>incdir</var></code></dt> 196 <dd>This option is directly passed through to the compilation command(s). 197 Use this to add your own include directories to search to the build 198 process.</dd> 199 200 <dt><code>-L <var>libdir</var></code></dt> 201 <dd>This option is directly passed through to the linker command. Use this 202 to add your own library directories to search to the build process.</dd> 203 204 <dt><code>-l <var>libname</var></code></dt> 205 <dd>This option is directly passed through to the linker command. Use this 206 to add your own libraries to search to the build process.</dd> 207 208 <dt><code>-Wc,<var>compiler-flags</var></code></dt> 209 <dd>This option passes <var>compiler-flags</var> as additional flags to 210 the <code>libtool --mode=compile</code> command. Use this to add local 211 compiler-specific options.</dd> 212 213 <dt><code>-Wl,<var>linker-flags</var></code></dt> 214 <dd>This option passes <var>linker-flags</var> as additional 215 flags to the <code>libtool --mode=link</code> command. Use this 216 to add local linker-specific options.</dd> 217 </dl> 218 219 220 <h3><a name="options.dsoinstall" id="options.dsoinstall">DSO Installation and Configuration Options</a></h3> 221 222 <dl> 223 <dt><code>-i</code></dt> 224 <dd>This indicates the installation operation and installs one or more 225 dynamically shared objects into the server's <var>modules</var> 226 directory.</dd> 227 228 <dt><code>-a</code></dt> 229 <dd>This activates the module by automatically adding a corresponding 230 <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> line to Apache's 231 <code>httpd.conf</code> configuration file, or by enabling it if it 232 already exists.</dd> 233 234 <dt><code>-A</code></dt> 235 <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 236 sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for 237 later activation but initially disabled.</dd> 238 239 <dt><code>-e</code></dt> 240 <dd>This indicates the editing operation, which can be used with the 241 <code>-a</code> and <code>-A</code> options similarly to the 242 <code>-i</code> operation to edit Apache's <code>httpd.conf</code> 243 configuration file without attempting to install the module.</dd> 244 </dl> 245 246</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 247<div class="section"> 248<h2><a name="examples" id="examples">Examples</a></h2> 249 <p>Assume you have an Apache module named <code>mod_foo.c</code> available 250 which should extend Apache's server functionality. To accomplish this you 251 first have to compile the C source into a shared object suitable for loading 252 into the Apache server under runtime via the following command:</p> 253 254 <div class="example"><p><code> 255 $ apxs -c mod_foo.c<br /> 256 /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br /> 257 /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br /> 258 $ _ 259 </code></p></div> 260 261 <p>Then you have to update the Apache configuration by making sure a 262 <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> directive is present to 263 load this shared object. To simplify this step <code>apxs</code> provides 264 an automatic way to install the shared object in its "modules" directory 265 and updating the <code>httpd.conf</code> file accordingly. This can be 266 achieved by running:</p> 267 268 <div class="example"><p><code> 269 $ apxs -i -a mod_foo.la<br /> 270 /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br /> 271 /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules 272 ... 273 chmod 755 /path/to/apache/modules/mod_foo.so<br /> 274 [activating module `foo' in /path/to/apache/conf/httpd.conf]<br /> 275 $ _ 276 </code></p></div> 277 278 <p>This way a line named</p> 279 280 <div class="example"><p><code> 281 LoadModule foo_module modules/mod_foo.so 282 </code></p></div> 283 284 <p>is added to the configuration file if still not present. If you want to 285 have this disabled per default use the <code>-A</code> option, 286 <em>i.e.</em></p> 287 288 <div class="example"><p><code> 289 $ apxs -i -A mod_foo.c 290 </code></p></div> 291 292 <p>For a quick test of the apxs mechanism you can create a sample Apache 293 module template plus a corresponding Makefile via:</p> 294 295 <div class="example"><p><code> 296 $ apxs -g -n foo<br /> 297 Creating [DIR] foo<br /> 298 Creating [FILE] foo/Makefile<br /> 299 Creating [FILE] foo/modules.mk<br /> 300 Creating [FILE] foo/mod_foo.c<br /> 301 Creating [FILE] foo/.deps<br /> 302 $ _ 303 </code></p></div> 304 305 <p>Then you can immediately compile this sample module into a shared object 306 and load it into the Apache server:</p> 307 308 <div class="example"><p><code> 309 $ cd foo<br /> 310 $ make all reload<br /> 311 apxs -c mod_foo.c<br /> 312 /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br /> 313 /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br /> 314 apxs -i -a -n "foo" mod_foo.la<br /> 315 /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br /> 316 /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules 317 ... 318 chmod 755 /path/to/apache/modules/mod_foo.so<br /> 319 [activating module `foo' in /path/to/apache/conf/httpd.conf]<br /> 320 apachectl restart<br /> 321 /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br /> 322 [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br /> 323 /path/to/apache/sbin/apachectl restart: httpd started<br /> 324 $ _ 325 </code></p></div> 326 327</div></div> 328<div class="bottomlang"> 329<p><span>Available Languages: </span><a href="/en/programs/apxs.html" title="English"> en </a> | 330<a href="/ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 331<a href="/tr/programs/apxs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 332</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 333<script type="text/javascript"><!--//--><![CDATA[//><!-- 334var comments_shortname = 'httpd'; 335var comments_identifier = 'http://httpd.apache.org/docs/2.2/programs/apxs.html'; 336(function(w, d) { 337 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 338 d.write('<div id="comments_thread"><\/div>'); 339 var s = d.createElement('script'); 340 s.type = 'text/javascript'; 341 s.async = true; 342 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 343 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 344 } 345 else { 346 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 347 } 348})(window, document); 349//--><!]]></script></div><div id="footer"> 350<p class="apache">Copyright 2013 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> 351<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 352if (typeof(prettyPrint) !== 'undefined') { 353 prettyPrint(); 354} 355//--><!]]></script> 356</body></html>
