apxs.html revision 5c16955d1899c4f64dee2523b71be8deb6c96c57
18c2aff776a775d34a4c9893a4c72e0434d68e36artem<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
18c2aff776a775d34a4c9893a4c72e0434d68e36artem "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <meta name="generator" content="HTML Tidy, see www.w3.org" />
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]" />
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <!-- This document was autogenerated from the man page -->
18c2aff776a775d34a4c9893a4c72e0434d68e36artem apxs - APache eXtenSion tool
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> -<strong>g</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] -<strong>n</strong> <em>modname</em>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> -<strong>q</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] <em>query</em> ...
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> -<strong>c</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>o</strong> <em>dsofile</em> ] [ -<strong>I</strong> <em>incdir</em> ] [ -<strong>D</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <em>name</em>=<em>value</em> ] [ -<strong>L</strong> <em>libdir</em> ] [ -<strong>l</strong> <em>libname</em> ] [ -<strong>Wc,</strong><em>compiler</em>-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <em>flags</em> ] [ -<strong>Wl,</strong><em>linker</em>-<em>flags</em> ] <em>files</em> ...
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> -<strong>i</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>n</strong> <em>modname</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> -<strong>e</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] [ -<strong>n</strong> <em>modname</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> is a tool for building and installing extension modules
18c2aff776a775d34a4c9893a4c72e0434d68e36artem for the Apache HyperText Transfer Protocol (HTTP) server.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This is achieved by building a dynamic shared object (DSO)
18c2aff776a775d34a4c9893a4c72e0434d68e36artem from one or more source or object <em>files</em> which then can be
18c2aff776a775d34a4c9893a4c72e0434d68e36artem loaded into the Apache server under runtime via the <strong>LoadMo-</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>dule</strong> directive from <strong>mod_so.</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem So to use this extension mechanism your platform has to sup-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem port the DSO feature and your Apache <strong>httpd</strong> binary has to be
18c2aff776a775d34a4c9893a4c72e0434d68e36artem built with the <strong>mod_so</strong> module. The <strong>apxs</strong> tool automatically
18c2aff776a775d34a4c9893a4c72e0434d68e36artem complains if this is not the case. You can check this your-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem self by manually running the command
18c2aff776a775d34a4c9893a4c72e0434d68e36artem The module <strong>mod_so</strong> should be part of the displayed list. If
18c2aff776a775d34a4c9893a4c72e0434d68e36artem these requirements are fulfilled you can easily extend your
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Apache server's functionality by installing your own modules
18c2aff776a775d34a4c9893a4c72e0434d68e36artem with the DSO mechanism by the help of this <strong>apxs</strong> tool:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ apxs -i -a -c mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem [activating module `foo' in /path/to/apache/etc/httpd.conf]
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ apachectl restart
18c2aff776a775d34a4c9893a4c72e0434d68e36artem /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
18c2aff776a775d34a4c9893a4c72e0434d68e36artem [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
18c2aff776a775d34a4c9893a4c72e0434d68e36artem The arguments <em>files</em> can be any C source file (.c), a object
18c2aff776a775d34a4c9893a4c72e0434d68e36artem file (.o) or even a library archive (.a). The <strong>apxs</strong> tool
18c2aff776a775d34a4c9893a4c72e0434d68e36artem automatically recognizes these extensions and automatically
18c2aff776a775d34a4c9893a4c72e0434d68e36artem used the C source files for compilation while just using the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem object and archive files for the linking phase. But when
18c2aff776a775d34a4c9893a4c72e0434d68e36artem using such pre-compiled objects make sure they are compiled
18c2aff776a775d34a4c9893a4c72e0434d68e36artem for position independent code (PIC) to be able to use them
18c2aff776a775d34a4c9893a4c72e0434d68e36artem for a dynamically loaded shared object. For instance with
18c2aff776a775d34a4c9893a4c72e0434d68e36artem GCC you always just have to use <strong>-fpic</strong>. For other C com-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem pilers consult its manual page or at watch for the flags
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>apxs</strong> uses to compile the object files.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem For more details about DSO support in Apache read the docu-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem mentation of <strong>mod_so</strong> or perhaps even read the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <strong>src/modules/standard/mod_so.c</strong> source file.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Common options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>n</strong> <em>modname</em> This explicitly sets the module name for the -<strong>i</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem (install) and -<strong>g</strong> (template generation) option.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Use this to explicitly specify the module name.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem For option -<strong>g</strong> this is required, for option -<strong>i</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the <strong>apxs</strong> tool tries to determine the name from
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the source or (as a fallback) at least by guess-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem ing it from the filename.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Query options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>q </strong> Performs a query for <strong>apxs</strong>'s knowledge about cer-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem tain settings. The <em>query</em> parameters can be one
18c2aff776a775d34a4c9893a4c72e0434d68e36artem or more of the following strings:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem CFLAGS SBINDIR
18c2aff776a775d34a4c9893a4c72e0434d68e36artem CFLAGS_SHLIB INCLUDEDIR
18c2aff776a775d34a4c9893a4c72e0434d68e36artem LD_SHLIB LIBEXECDIR
18c2aff776a775d34a4c9893a4c72e0434d68e36artem LDFLAGS_SHLIB SYSCONFDIR
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Use this for manually determining settings. For
18c2aff776a775d34a4c9893a4c72e0434d68e36artem instance use
18c2aff776a775d34a4c9893a4c72e0434d68e36artem INC=-I`apxs -q INCLUDEDIR`
18c2aff776a775d34a4c9893a4c72e0434d68e36artem inside your own Makefiles if you need manual
18c2aff776a775d34a4c9893a4c72e0434d68e36artem access to Apache's C header files.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Configuration options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This option changes the apxs settings described
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Template Generation options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>g </strong> This generates a subdirectory <em>name</em> (see option
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>n</strong>) and there two files: A sample module source
18c2aff776a775d34a4c9893a4c72e0434d68e36artem file named <strong>mod_</strong><em>name</em>.<em>c</em> which can be used as a
18c2aff776a775d34a4c9893a4c72e0434d68e36artem template for creating your own modules or as a
18c2aff776a775d34a4c9893a4c72e0434d68e36artem quick start for playing with the APXS mechanism.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem And a corresponding <strong>Makefile</strong> for even easier
18c2aff776a775d34a4c9893a4c72e0434d68e36artem build and installing of this module.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem DSO compilation options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>c </strong> This indicates the compilation operation. It
18c2aff776a775d34a4c9893a4c72e0434d68e36artem first compiles the C source files (.c) of <em>files</em>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem into corresponding object files (.o) and then
18c2aff776a775d34a4c9893a4c72e0434d68e36artem builds a dynamically shared object in <em>dsofile</em> by
18c2aff776a775d34a4c9893a4c72e0434d68e36artem linking these object files plus the remaining
18c2aff776a775d34a4c9893a4c72e0434d68e36artem object files (.o and .a) of <em>files</em> If no -<strong>o</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem option is specified the output file is guessed
18c2aff776a775d34a4c9893a4c72e0434d68e36artem from the first filename in <em>files</em> and thus usu-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem ally defaults to <strong>mod_</strong><em>name</em>.<em>so</em>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>o</strong> <em>dsofile</em> Explicitly specifies the filename of the created
18c2aff776a775d34a4c9893a4c72e0434d68e36artem dynamically shared object. If not specified and
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the name cannot be guessed from the <em>files</em> list,
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the fallback name <strong>mod_unknown.so</strong> is used.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This option is directly passed through to the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem compilation command(s). Use this to add your
18c2aff776a775d34a4c9893a4c72e0434d68e36artem own defines to the build process.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>I</strong> <em>incdir</em> This option is directly passed through to the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem compilation command(s). Use this to add your
18c2aff776a775d34a4c9893a4c72e0434d68e36artem own include directories to search to the build
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>L</strong> <em>libdir</em> This option is directly passed through to the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem linker command. Use this to add your own
18c2aff776a775d34a4c9893a4c72e0434d68e36artem library directories to search to the build pro-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>l</strong> <em>libname</em> This option is directly passed through to the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem linker command. Use this to add your own
18c2aff776a775d34a4c9893a4c72e0434d68e36artem libraries to search to the build process.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This option passes <em>compiler</em>-<em>flags</em> as additional
18c2aff776a775d34a4c9893a4c72e0434d68e36artem flags to the compiler command. Use this to add
18c2aff776a775d34a4c9893a4c72e0434d68e36artem local compiler-specific options.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This option passes <em>linker</em>-<em>flags</em> as additional
18c2aff776a775d34a4c9893a4c72e0434d68e36artem flags to the linker command. Use this to add
18c2aff776a775d34a4c9893a4c72e0434d68e36artem local linker-specific options.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem DSO installation and configuration options:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>i </strong> This indicates the installation operation and
18c2aff776a775d34a4c9893a4c72e0434d68e36artem installs one or more dynamically shared objects
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>a </strong> This activates the module by automatically
18c2aff776a775d34a4c9893a4c72e0434d68e36artem adding a corresponding <strong>LoadModule</strong> line to
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Apache's <strong>httpd.conf</strong> configuration file, or by
18c2aff776a775d34a4c9893a4c72e0434d68e36artem enabling it if it already exists.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>A </strong> Same as option -<strong>a</strong> but the created <strong>LoadModule</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem directive is prefixed with a hash sign (#), i.e.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the module is just prepared for later activation
18c2aff776a775d34a4c9893a4c72e0434d68e36artem but initially disabled.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem -<strong>e </strong> This indicates the editing operation, which can
18c2aff776a775d34a4c9893a4c72e0434d68e36artem be used with the -<strong>a</strong> and -<strong>A</strong> options similarly to
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the -<strong>i</strong> operation to edit Apache's <strong>httpd.conf</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem configuration file without attempting to install
18c2aff776a775d34a4c9893a4c72e0434d68e36artem the module.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Assume you have an Apache module named mod_foo.c available
18c2aff776a775d34a4c9893a4c72e0434d68e36artem which should extend Apache's server functionality. To accom-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem plish this you first have to compile the C source into a
18c2aff776a775d34a4c9893a4c72e0434d68e36artem shared object suitable for loading into the Apache server
18c2aff776a775d34a4c9893a4c72e0434d68e36artem under runtime via the following command:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Then you have to update the Apache configuration by making
18c2aff776a775d34a4c9893a4c72e0434d68e36artem sure a <strong>LoadModule</strong> directive is present to load this shared
18c2aff776a775d34a4c9893a4c72e0434d68e36artem object. To simplify this step <strong>apxs</strong> provides an automatic way
18c2aff776a775d34a4c9893a4c72e0434d68e36artem to install the shared object in its "modules" directory and
18c2aff776a775d34a4c9893a4c72e0434d68e36artem updating the <strong>httpd.conf</strong> file accordingly. This can be
18c2aff776a775d34a4c9893a4c72e0434d68e36artem achieved by running:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ apxs -i -a mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem [activating module `foo' in /path/to/apache/etc/httpd.conf]
18c2aff776a775d34a4c9893a4c72e0434d68e36artem This way a line named
18c2aff776a775d34a4c9893a4c72e0434d68e36artem is added to the configuration file if still not present. If
18c2aff776a775d34a4c9893a4c72e0434d68e36artem you want to have this disabled per default use the -<strong>A</strong>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ apxs -i -A mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem For a quick test of the APXS mechanism you can create a sam-
18c2aff776a775d34a4c9893a4c72e0434d68e36artem ple Apache module template plus a corresponding Makefile
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ apxs -g -n foo
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Creating [DIR] foo
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Then you can immediately compile this sample module into a
18c2aff776a775d34a4c9893a4c72e0434d68e36artem shared object and load it into the Apache server:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem $ make all reload
18c2aff776a775d34a4c9893a4c72e0434d68e36artem gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem apxs -i -a -n "foo" mod_foo.so
18c2aff776a775d34a4c9893a4c72e0434d68e36artem [activating module `foo' in /path/to/apache/etc/httpd.conf]
18c2aff776a775d34a4c9893a4c72e0434d68e36artem apachectl restart
18c2aff776a775d34a4c9893a4c72e0434d68e36artem /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
18c2aff776a775d34a4c9893a4c72e0434d68e36artem [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
18c2aff776a775d34a4c9893a4c72e0434d68e36artem You can even use <strong>apxs</strong> to compile complex modules outside the
18c2aff776a775d34a4c9893a4c72e0434d68e36artem Apache source tree, like PHP3:
18c2aff776a775d34a4c9893a4c72e0434d68e36artem gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c
18c2aff776a775d34a4c9893a4c72e0434d68e36artem ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
18c2aff776a775d34a4c9893a4c72e0434d68e36artem because <strong>apxs</strong> automatically recognized C source files and
18c2aff776a775d34a4c9893a4c72e0434d68e36artem object files. Only C source files are compiled while
18c2aff776a775d34a4c9893a4c72e0434d68e36artem remaining object files are used for the linking phase.
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <h3 align="center">Apache HTTP Server Version 2.1</h3>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <a href="./"><img src="/images/index.gif" alt="Index" /></a>
18c2aff776a775d34a4c9893a4c72e0434d68e36artem <a href="../"><img src="/images/home.gif" alt="Home" /></a>
