SUMMARY apxs is a tool for building and installing
extension modules for the Apache HyperText Transfer Protocol
(HTTP) server. This is achieved by building a dynamic shared
object (DSO) from one or more source or object files which
then can be loaded into the Apache server under run- time
via the LoadModule directive from mod_so.

So to use this extension mechanism your platform has to
support the DSO feature and your Apache httpd binary has to
be built with the mod_so module. The apxs tool automatically
complains if this is not the case. You can check this
yourself by manually running the command

$ httpd -l

The module mod_so should be part of the displayed list.
If these requirements are fulfilled you can easily extend
your Apache servers functionality by installing your own
modules with the DSO mechanism by the help of this apxs
tool:

The arguments files can be any C source file (.c), a
object file (.o) or even a library archive (.a). The apxs
tool automatically recognizes these extensions and
automatically used the C source files for compila- tion
while just using the object and archive files for the
linking phase. But when using such pre-compiled objects make
sure they are com- piled 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
-fpic. For other C compilers consult its manual page or at
watch for the flags apxs uses to compile the object
files.

For more details about DSO support in Apache read the
documentation of mod_so or perhaps even read the
src/modules/standard/mod_so.c source file.

OPTIONS Common Options -n modname This explicitly sets
the module name for the -i (install) and -g (template
generation) option. Use this to explicitly specify the
module name. For option -g this is required, for option -i
the apxs tool tries to determine the name from the source or
(as a fallback) at least by guessing it from the
filename.

Query Options -q Performs a query for apxs s knowledge
about certain settings. The query parameters can be one or
more of the following strings: CC, CFLAGS, CFLAGS_SHLIB,
INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB,
SBINDIR, SYSCONFDIR, TAR- GET. .PP Use this for manually
determining settings. For instance use INC=-Iapxs -q
INCLUDEDIR .PP inside your own Makefiles if you need manual
access to Apache s C header files.

Template Generation Options -g This generates a
subdirectory name (see option -n) and there two files: A
sample module source file named mod_name.c 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 Makefile for even easier build and installing
of this module.

DSO Compilation Options -c This indicates the
compilation operation. It first compiles the C source files
(.c) of files into corresponding object files (.o) and then
builds a dynamically shared object in dsofile by linking
these object files plus the remaining object files (.o and
.a) of files. If no -o option is specified the output file
is guessed from the first filename in files and thus usually
defaults to mod_name.so.

-o dsofile Explicitly specifies the filename of the
created dynamically shared object. If not specified and the
name cannot be guessed from the files list, the fallback
name mod_unknown.so is used.

-D name=value This option is directly passed through to
the compilation com- mand(s). Use this to add your own
defines to the build process.

-I incdir This option is directly passed through to the
compilation com- mand(s). Use this to add your own include
directories to search to the build process.

-L libdir This option is directly passed through to the
linker command. Use this to add your own library directories
to search to the build process.

-l libname This option is directly passed through to the
linker command. Use this to add your own libraries to search
to the build pro- cess.

-Wc,compiler-flags This option passes compiler-flags as
additional flags to the libtool --mode=compile command. Use
this to add local compiler- specific options.

-Wl,linker-flags This option passes linker-flags as
additional flags to the libtool --mode=link command. Use
this to add local linker-spe- cific options.

DSO Installation and Configuration Options -i This
indicates the installation operation and installs one or
more dynamically shared objects into the servers modules
direc- tory.

-a This activates the module by automatically adding a
correspond- ing LoadModule line to Apache s httpd.conf
configuration file, or by enabling it if it already
exists.

-A Same as option -a but the created LoadModule
directive is pre- fixed with a hash sign (#), i.e., the
module is just prepared for later activation but initially
disabled.

-e This indicates the editing operation, which can be
used with the -a and -A options similarly to the -i
operation to edit Apaches httpd.conf configuration file
without attempting to install the module.

EXAMPLES Assume you have an Apache module named
mod_foo.c available which should extend Apaches server
functionality. To accomplish 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:

Then you have to update the Apache configuration by
making sure a Load- Module directive is present to load this
shared object. To simplify this step apxs provides an
automatic way to install the shared object in its
"modules" directory and updating the httpd.conf
file accord- ingly. This can be achieved by running: