1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 4<html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 7 8 <title>Manual Page: apxs - Apache HTTP Server</title> 9 </head> 10 11 <body bgcolor="#ffffff" text="#000000" link="#0000ff" 12 vlink="#000080" alink="#ff0000"> 13 <div align="CENTER"> 14 <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 15 16 <h3>Apache HTTP Server Version 1.3</h3> 17 </div> 18 19 20 <h1 align="center">Manual Page: apxs</h1> 21 <!-- This document was autogenerated from the man page --> 22<pre> 23<strong>NAME</strong> 24 apxs - APache eXtenSion tool 25 26<strong>SYNOPSIS</strong> 27 <strong>apxs</strong> -<strong>g</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] -<strong>n</strong> <em>name</em> 28 29 <strong>apxs</strong> -<strong>q</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] <em>query</em> ... 30 31 <strong>apxs</strong> -<strong>c</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>o</strong> <em>dsofile</em> ] [ -<strong>I</strong> <em>incdir</em> ] [ 32 -<strong>D</strong> <em>variable</em>[=<em>value</em>] ] [ -<strong>L</strong> <em>libdir</em> ] [ -<strong>l</strong> <em>libname</em> ] [ 33 -<strong>Wc,</strong><em>compiler</em>-<em>flags</em> ] [ -<strong>Wl,</strong><em>linker</em>-<em>flags</em> ] <em>files</em> ... 34 35 <strong>apxs</strong> -<strong>i</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>n</strong> <em>name</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em> 36 <em>file</em> ... 37 38 <strong>apxs</strong> -<strong>e</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>n</strong> <em>name</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em> 39 <em>file</em> ... 40 41<strong>DESCRIPTION</strong> 42 <strong>apxs</strong> is a tool for building and installing extension modules 43 for the Apache HyperText Transfer Protocol (HTTP) server. 44 This is achieved by building a Dynamic Shared Object (DSO) 45 from one or more source or object <em>files</em> which then can be 46 loaded into the Apache server under runtime via the <strong>LoadMo-</strong> 47 <strong>dule</strong> directive from <strong>mod_so.</strong> 48 49 So to use this extension mechanism, your platform has to 50 support the DSO feature and your Apache <strong>httpd</strong> binary has to 51 be built with the <strong>mod_so</strong> module. The <strong>apxs</strong> tool automati- 52 cally complains if this is not the case. You can check this 53 yourself by manually running the command 54 55 $ httpd -l 56 57 The module <strong>mod_so</strong> should be part of the displayed list. If 58 these requirements are fulfilled, you can easily extend your 59 Apache server's functionality by installing your own modules 60 with the DSO mechanism by the help of this <strong>apxs</strong> tool: 61 62 $ apxs -i -a -c mod_foo.c 63 gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c 64 ld -Bshareable -o mod_foo.so mod_foo.o 65 cp mod_foo.so /path/to/apache/libexec/mod_foo.so 66 chmod 755 /path/to/apache/libexec/mod_foo.so 67 [activating module `foo' in /path/to/apache/etc/httpd.conf] 68 $ apachectl restart 69 /path/to/apache/sbin/apachectl restart: httpd not running, trying to start 70 [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module 71 /path/to/apache/sbin/apachectl restart: httpd started 72 $ _ 73 74 The arguments <em>files</em> can be any C source file (.c), a object 75 file (.o) or even a library archive (.a). The <strong>apxs</strong> tool 76 automatically recognizes these extensions and automatically 77 uses the C source files for compilation while it just uses 78 the object and archive files for the linking phase. But when 79 using such pre-compiled objects, make sure they are compiled 80 for Position Independent Code (PIC) to be able to use them 81 for a DSO. For instance with GCC you always just have to use 82 <strong>-fpic</strong>. For other C compilers please consult its manual page 83 or watch for the flags <strong>apxs</strong> uses to compile the object 84 files. 85 86 For more details about DSO support in Apache, first read the 87 background information about DSO in htdocs/manual/dso.html, 88 then read the documentation of <strong>mod_so</strong>. 89 90<strong>OPTIONS</strong> 91 Common options: 92 93 -<strong>n</strong> <em>name </em> This explicitly sets the module name for the -<strong>i</strong> 94 (install) and -<strong>g</strong> (template generation) option. 95 Use this to explicitly specify the module name. 96 For option -<strong>g</strong> this is required, for option -<strong>i</strong> 97 the <strong>apxs</strong> tool tries to determine the name from 98 the source or (as a fallback) at least by guess- 99 ing it from the filename. 100 101 Query options: 102 103 -<strong>q </strong> Performs a query for <strong>apxs</strong>'s knowledge about cer- 104 tain settings. The <em>query</em> parameters can be one 105 or more of the following variable names: 106 CC TARGET 107 CFLAGS SBINDIR 108 CFLAGS_SHLIB INCLUDEDIR 109 LD_SHLIB LIBEXECDIR 110 LDFLAGS_SHLIB SYSCONFDIR 111 LIBS_SHLIB PREFIX 112 Use this for manually determining settings. For 113 instance use 114 INC=-I`apxs -q INCLUDEDIR` 115 inside your own Makefiles if you need manual 116 access to Apache's C header files. 117 118 Configuration options: 119 120 -<strong>S</strong> <em>variable</em>=<em>value</em> 121 This option changes the <strong>apxs</strong> settings described 122 above. 123 124 Template Generation options: 125 -<strong>g </strong> This generates a subdirectory <em>name</em> (see option 126 -<strong>n</strong>) and there two files: A sample module source 127 file named <strong>mod_</strong><em>name</em>.<em>c</em> which can be used as a 128 template for creating your own modules or as a 129 quick start for playing with the <strong>apxs</strong> mechanism. 130 And a corresponding <strong>Makefile</strong> for even easier 131 building and installing of this module. 132 133 DSO compilation options: 134 135 -<strong>c </strong> This indicates the compilation operation. It 136 first compiles the C source files (.c) of <em>files</em> 137 into corresponding object files (.o) and then 138 builds a DSO in <em>dsofile</em> by linking these object 139 files plus the remaining object files (.o and 140 .a) of <em>files</em> If no -<strong>o</strong> option is specified the 141 output file is guessed from the first filename 142 in <em>files</em> and thus usually defaults to 143 <strong>mod_</strong><em>name</em>.<em>so</em> 144 145 -<strong>o</strong> <em>dsofile</em> Explicitly specifies the filename of the created 146 DSO file. If not specified and the name cannot 147 be guessed from the <em>files</em> list, the fallback 148 name <strong>mod_unknown.so</strong> is used. 149 150 -<strong>D</strong> <em>variable</em>[=<em>value</em>] 151 This option is directly passed through to the 152 compilation command(s). Use this to add your 153 own defines to the build process. 154 155 -<strong>I</strong> <em>incdir</em> This option is directly passed through to the 156 compilation command(s). Use this to add your 157 own include directories to search to the build 158 process. 159 160 -<strong>L</strong> <em>libdir</em> This option is directly passed through to the 161 linker command. Use this to add your own 162 library directories to search to the build pro- 163 cess. 164 165 -<strong>l</strong> <em>libname</em> This option is directly passed through to the 166 linker command. Use this to add your own 167 libraries to search to the build process. 168 169 -<strong>Wc,</strong><em>compiler</em>-<em>flags</em> 170 This option passes <em>compiler</em>-<em>flags</em> as additional 171 flags to the compiler command. Use this to add 172 local compiler-specific options. 173 174 -<strong>Wl,</strong><em>linker</em>-<em>flags</em> 175 This option passes <em>linker</em>-<em>flags</em> as additional 176 flags to the linker command. Use this to add 177 local linker-specific options. 178 179 DSO installation and configuration options: 180 181 -<strong>i </strong> This indicates the installation operation and 182 installs one or more DSOs into the server's 183 <em>libexec</em> directory. 184 185 -<strong>a </strong> This activates the module by automatically 186 adding a corresponding <strong>LoadModule</strong> line to 187 Apache's <strong>httpd.conf</strong> configuration file, or by 188 enabling it if it already exists. 189 190 -<strong>A </strong> Same as option -<strong>a</strong> but the created <strong>LoadModule</strong> 191 directive is prefixed with a hash sign (#), i.e. 192 the module is just prepared for later activation 193 but initially disabled. 194 195 -<strong>e </strong> This indicates the editing operation, which can 196 be used with the -<strong>a</strong> and -<strong>A</strong> options similarly to 197 the -<strong>i</strong> operation to edit Apache's <strong>httpd.conf</strong> 198 configuration file without attempting to install 199 the module. 200 201<strong>EXAMPLES</strong> 202 Assume you have an Apache module named mod_foo.c available 203 which should extend Apache's server functionality. To accom- 204 plish this you first have to compile the C source into a DSO 205 suitable for loading into the Apache server under runtime 206 via the following command: 207 208 $ apxs -c mod_foo.c 209 gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c 210 ld -Bshareable -o mod_foo.so mod_foo.o 211 $ _ 212 213 Then you have to update the Apache configuration by making 214 sure a <strong>LoadModule</strong> directive is present to load this DSO. To 215 simplify this step <strong>apxs</strong> provides an automatic way to install 216 the DSO in the "libexec" directory and updating the 217 <strong>httpd.conf</strong> file accordingly. This can be achieved by run- 218 ning: 219 220 $ apxs -i -a mod_foo.c 221 cp mod_foo.so /path/to/apache/libexec/mod_foo.so 222 chmod 755 /path/to/apache/libexec/mod_foo.so 223 [activating module `foo' in /path/to/apache/etc/httpd.conf] 224 $ _ 225 226 This way a line named 227 228 LoadModule foo_module libexec/mod_foo.so 229 230 is added to the configuration file if still not present. If 231 you want to have this operation to be disabled, use the -<strong>A</strong> 232 option, i.e. 233 234 $ apxs -i -A mod_foo.c 235 236 For a quick test of the <strong>apxs</strong> mechanism you can create a sam- 237 ple Apache module template plus a corresponding <strong>Makefile</strong> 238 via: 239 240 $ apxs -g -n foo 241 Creating [DIR] foo 242 Creating [FILE] foo/Makefile 243 Creating [FILE] foo/mod_foo.c 244 $ _ 245 246 Then you can immediately compile this sample module into a 247 DSO and load it into the Apache server: 248 249 $ cd foo 250 $ make all reload 251 apxs -c mod_foo.c 252 gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c 253 ld -Bshareable -o mod_foo.so mod_foo.o 254 apxs -i -a -n "foo" mod_foo.so 255 cp mod_foo.so /path/to/apache/libexec/mod_foo.so 256 chmod 755 /path/to/apache/libexec/mod_foo.so 257 [activating module `foo' in /path/to/apache/etc/httpd.conf] 258 apachectl restart 259 /path/to/apache/sbin/apachectl restart: httpd not running, trying to start 260 [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module 261 /path/to/apache/sbin/apachectl restart: httpd started 262 $ _ 263 264 You can even use <strong>apxs</strong> to compile complex modules outside the 265 Apache source tree, like PHP3, because <strong>apxs</strong> automatically 266 recognized C source files and object files. 267 268 $ cd php3 269 $ ./configure --with-shared-apache=../apache-1.3 270 $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a 271 gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c 272 ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a 273 $ _ 274 275 Only C source files are compiled while remaining object 276 files are used for the linking phase. 277 278<strong>SEE ALSO</strong> 279 <strong>apachectl(1), httpd(8).</strong> 280 281</pre> 282 <hr /> 283 284 <h3 align="CENTER">Apache HTTP Server Version 1.3</h3> 285 <a href="./"><img src="../images/index.gif" alt="Index" /></a> 286 <a href="../"><img src="../images/home.gif" alt="Home" /></a> 287 288 289 </body> 290</html> 291 292
