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.min.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.4</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.4</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="/fr/programs/apxs.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 26<a href="/ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 27<a href="/tr/programs/apxs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 28</div> 29 30 <p><code>apxs</code> is a tool for building and installing extension 31 modules for the Apache HyperText Transfer Protocol (HTTP) server. This is 32 achieved by building a dynamic shared object (DSO) from one or more source 33 or object <var>files</var> which then can be loaded into the Apache server 34 under runtime via the <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> 35 directive from <code class="module"><a href="/mod/mod_so.html">mod_so</a></code>.</p> 36 37 <p>So to use this extension mechanism your platform has to support the DSO 38 feature and your Apache <code class="program"><a href="/programs/httpd.html">httpd</a></code> binary has to be built with the 39 <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> module. The <code>apxs</code> tool automatically 40 complains if this is not the case. You can check this yourself by manually 41 running the command</p> 42 43 <div class="example"><p><code> 44 $ httpd -l 45 </code></p></div> 46 47 <p>The module <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> should be part of the displayed list. 48 If these requirements are fulfilled you can easily extend your Apache 49 server's functionality by installing your own modules with the DSO mechanism 50 by the help of this <code>apxs</code> tool:</p> 51 52 <div class="example"><p><code> 53 $ apxs -i -a -c mod_foo.c<br /> 54 gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br /> 55 ld -Bshareable -o mod_foo.so mod_foo.o<br /> 56 cp mod_foo.so /path/to/apache/modules/mod_foo.so<br /> 57 chmod 755 /path/to/apache/modules/mod_foo.so<br /> 58 [activating module `foo' in /path/to/apache/etc/httpd.conf]<br /> 59 $ apachectl restart<br /> 60 /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br /> 61 [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br /> 62 /path/to/apache/sbin/apachectl restart: httpd started<br /> 63 $ _ 64 </code></p></div> 65 66 <p>The arguments <var>files</var> can be any C source file (.c), a object 67 file (.o) or even a library archive (.a). The <code>apxs</code> tool 68 automatically recognizes these extensions and automatically used the C 69 source files for compilation while just using the object and archive files 70 for the linking phase. But when using such pre-compiled objects make sure 71 they are compiled for position independent code (PIC) to be able to use them 72 for a dynamically loaded shared object. For instance with GCC you always 73 just have to use <code>-fpic</code>. For other C compilers consult its 74 manual page or at watch for the flags <code>apxs</code> uses to compile the 75 object files.</p> 76 77 <p>For more details about DSO support in Apache read the documentation of 78 <code class="module"><a href="/mod/mod_so.html">mod_so</a></code> or perhaps even read the 79 <code>src/modules/standard/mod_so.c</code> source file.</p> 80</div> 81<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#synopsis">Synopsis</a></li> 82<li><img alt="" src="/images/down.gif" /> <a href="#options">Options</a></li> 83<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li> 84</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> 85<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 86<div class="section"> 87<h2><a name="synopsis" id="synopsis">Synopsis</a></h2> 88 <p><code><strong>apxs</strong> -<strong>g</strong> 89 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 90 -<strong>n</strong> <var>modname</var></code></p> 91 92 <p><code><strong>apxs</strong> -<strong>q</strong> 93 [ -<strong>v</strong> ] 94 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 95 <var>query</var> ...</code></p> 96 97 <p><code><strong>apxs</strong> -<strong>c</strong> 98 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 99 [ -<strong>o</strong> <var>dsofile</var> ] 100 [ -<strong>I</strong> <var>incdir</var> ] 101 [ -<strong>D</strong> <var>name</var>=<var>value</var> ] 102 [ -<strong>L</strong> <var>libdir</var> ] 103 [ -<strong>l</strong> <var>libname</var> ] 104 [ -<strong>Wc,</strong><var>compiler-flags</var> ] 105 [ -<strong>Wl,</strong><var>linker-flags</var> ] 106 <var>files</var> ...</code></p> 107 108 <p><code><strong>apxs</strong> -<strong>i</strong> 109 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 110 [ -<strong>n</strong> <var>modname</var> ] 111 [ -<strong>a</strong> ] 112 [ -<strong>A</strong> ] 113 <var>dso-file</var> ...</code></p> 114 115 <p><code><strong>apxs</strong> -<strong>e</strong> 116 [ -<strong>S</strong> <var>name</var>=<var>value</var> ] 117 [ -<strong>n</strong> <var>modname</var> ] 118 [ -<strong>a</strong> ] 119 [ -<strong>A</strong> ] 120 <var>dso-file</var> ...</code></p> 121</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 122<div class="section"> 123<h2><a name="options" id="options">Options</a></h2> 124 <h3><a name="options.common" id="options.common">Common Options</a></h3> 125 <dl> 126 <dt><code>-n <var>modname</var></code></dt> 127 <dd>This explicitly sets the module name for the <code>-i</code> (install) 128 and <code>-g</code> (template generation) option. Use this to explicitly 129 specify the module name. For option <code>-g</code> this is required, for 130 option <code>-i</code> the <code>apxs</code> tool tries to determine the 131 name from the source or (as a fallback) at least by guessing it from the 132 filename.</dd> 133 </dl> 134 135 136 <h3><a name="options.query" id="options.query">Query Options</a></h3> 137 <dl> 138 <dt><code>-q</code></dt> 139 <dd>Performs a query for variables and environment settings used to 140 build <code>httpd</code>. When invoked without <var>query</var> parameters, 141 it prints all known variables and their values. The optional <code>-v</code> 142 parameter formats the list output. 143 144 <p>Use this to manually determine settings used to build the 145 <code>httpd</code> that will load your module. 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 218 <dt><code>-p</code></dt> 219 <dd>This option causes apxs to link against the apr/apr-util libraries. 220 This is useful when compiling helper programs that use the apr/apr-util 221 libraries.</dd> 222 </dl> 223 224 225 <h3><a name="options.dsoinstall" id="options.dsoinstall">DSO Installation and Configuration Options</a></h3> 226 227 <dl> 228 <dt><code>-i</code></dt> 229 <dd>This indicates the installation operation and installs one or more 230 dynamically shared objects into the server's <var>modules</var> 231 directory.</dd> 232 233 <dt><code>-a</code></dt> 234 <dd>This activates the module by automatically adding a corresponding 235 <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> line to Apache's 236 <code>httpd.conf</code> configuration file, or by enabling it if it 237 already exists.</dd> 238 239 <dt><code>-A</code></dt> 240 <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 241 sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for 242 later activation but initially disabled.</dd> 243 244 <dt><code>-e</code></dt> 245 <dd>This indicates the editing operation, which can be used with the 246 <code>-a</code> and <code>-A</code> options similarly to the 247 <code>-i</code> operation to edit Apache's <code>httpd.conf</code> 248 configuration file without attempting to install the module.</dd> 249 </dl> 250 251</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 252<div class="section"> 253<h2><a name="examples" id="examples">Examples</a></h2> 254 <p>Assume you have an Apache module named <code>mod_foo.c</code> available 255 which should extend Apache's server functionality. To accomplish this you 256 first have to compile the C source into a shared object suitable for loading 257 into the Apache server under runtime via the following command:</p> 258 259 <div class="example"><p><code> 260 $ apxs -c mod_foo.c<br /> 261 /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br /> 262 /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br /> 263 $ _ 264 </code></p></div> 265 266 <p>Then you have to update the Apache configuration by making sure a 267 <code class="directive"><a href="/mod/mod_so.html#loadmodule">LoadModule</a></code> directive is present to 268 load this shared object. To simplify this step <code>apxs</code> provides 269 an automatic way to install the shared object in its "modules" directory 270 and updating the <code>httpd.conf</code> file accordingly. This can be 271 achieved by running:</p> 272 273 <div class="example"><p><code> 274 $ apxs -i -a mod_foo.la<br /> 275 /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br /> 276 /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules 277 ... 278 chmod 755 /path/to/apache/modules/mod_foo.so<br /> 279 [activating module `foo' in /path/to/apache/conf/httpd.conf]<br /> 280 $ _ 281 </code></p></div> 282 283 <p>This way a line named</p> 284 285 <div class="example"><p><code> 286 LoadModule foo_module modules/mod_foo.so 287 </code></p></div> 288 289 <p>is added to the configuration file if still not present. If you want to 290 have this disabled per default use the <code>-A</code> option, 291 <em>i.e.</em></p> 292 293 <div class="example"><p><code> 294 $ apxs -i -A mod_foo.c 295 </code></p></div> 296 297 <p>For a quick test of the apxs mechanism you can create a sample Apache 298 module template plus a corresponding Makefile via:</p> 299 300 <div class="example"><p><code> 301 $ apxs -g -n foo<br /> 302 Creating [DIR] foo<br /> 303 Creating [FILE] foo/Makefile<br /> 304 Creating [FILE] foo/modules.mk<br /> 305 Creating [FILE] foo/mod_foo.c<br /> 306 Creating [FILE] foo/.deps<br /> 307 $ _ 308 </code></p></div> 309 310 <p>Then you can immediately compile this sample module into a shared object 311 and load it into the Apache server:</p> 312 313 <div class="example"><p><code> 314 $ cd foo<br /> 315 $ make all reload<br /> 316 apxs -c mod_foo.c<br /> 317 /path/to/libtool --mode=compile gcc ... -c mod_foo.c<br /> 318 /path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo<br /> 319 apxs -i -a -n "foo" mod_foo.la<br /> 320 /path/to/instdso.sh mod_foo.la /path/to/apache/modules<br /> 321 /path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules 322 ... 323 chmod 755 /path/to/apache/modules/mod_foo.so<br /> 324 [activating module `foo' in /path/to/apache/conf/httpd.conf]<br /> 325 apachectl restart<br /> 326 /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br /> 327 [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br /> 328 /path/to/apache/sbin/apachectl restart: httpd started<br /> 329 $ _ 330 </code></p></div> 331 332</div></div> 333<div class="bottomlang"> 334<p><span>Available Languages: </span><a href="/en/programs/apxs.html" title="English"> en </a> | 335<a href="/fr/programs/apxs.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 336<a href="/ko/programs/apxs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 337<a href="/tr/programs/apxs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 338</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> 339<script type="text/javascript"><!--//--><![CDATA[//><!-- 340var comments_shortname = 'httpd'; 341var comments_identifier = 'http://httpd.apache.org/docs/2.4/programs/apxs.html'; 342(function(w, d) { 343 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 344 d.write('<div id="comments_thread"><\/div>'); 345 var s = d.createElement('script'); 346 s.type = 'text/javascript'; 347 s.async = true; 348 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 349 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 350 } 351 else { 352 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 353 } 354})(window, document); 355//--><!]]></script></div><div id="footer"> 356<p class="apache">Copyright 2014 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> 357<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[//><!-- 358if (typeof(prettyPrint) !== 'undefined') { 359 prettyPrint(); 360} 361//--><!]]></script> 362</body></html>
