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