Apache HTTP Server 2.1 Documentation Status File.
-Last modified: $Date: 2003/04/23 17:17:49 $
+Last modified: $Date: 2003/04/29 23:07:52 $
For more information on how to contribute to the Apache Documentation
Project, please see http://httpd.apache.org/docs-project/
developer/API.html
# converting from nroff to xml
-programs/ab.html
-programs/apxs.html
programs/dbmmanage.html
programs/htdigest.html
programs/htpasswd.html
programs/other.html
-programs/suexec.html
-.TH apxs 8 "April 1998"
-.\" The Apache Software License, Version 1.1
-.\"
-.\" Copyright (c) 2000-2003 The Apache Software Foundation. All rights
-.\" reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in
-.\" the documentation and/or other materials provided with the
-.\" distribution.
-.\"
-.\" 3. The end-user documentation included with the redistribution,
-.\" if any, must include the following acknowledgment:
-.\" "This product includes software developed by the
-.\" Apache Software Foundation (http://www.apache.org/)."
-.\" Alternately, this acknowledgment may appear in the software itself,
-.\" if and wherever such third-party acknowledgments normally appear.
-.\"
-.\" 4. The names "Apache" and "Apache Software Foundation" must
-.\" not be used to endorse or promote products derived from this
-.\" software without prior written permission. For written
-.\" permission, please contact apache@apache.org.
-.\"
-.\" 5. Products derived from this software may not be called "Apache",
-.\" nor may "Apache" appear in their name, without prior written
-.\" permission of the Apache Software Foundation.
-.\"
-.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
-.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-.\" DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" This software consists of voluntary contributions made by many
-.\" individuals on behalf of the Apache Software Foundation. For more
-.\" information on the Apache Software Foundation, please see
-.\" <http://www.apache.org/>.
-.\"
+.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+.\" DO NOT EDIT! Generated from XML source.
+.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "APXS" 8 "2003-04-29" "Apache HTTP Server" "apxs"
+
.SH NAME
apxs \- APache eXtenSion tool
-.SH SYNOPSIS
-.B apxs
-.B \-g
-[
-.BI \-S " name=value
-]
-.BI \-n " modname"
-
-.B apxs
-.B \-q
-[
-.BI \-S " name=value
-]
-.IR query " ..."
-.B apxs
-.B \-c
-[
-.BI \-S " name=value
-]
-[
-.BI \-o " dsofile"
-]
-[
-.BI \-I " incdir"
-]
-[
-.BI \-D " name=value"
-]
-[
-.BI \-L " libdir"
-]
-[
-.BI \-l " libname"
-]
-[
-.BI \-Wc, "compiler-flags"
-]
-[
-.BI \-Wl, "linker-flags"
-]
-.IR files " ..."
-
-.B apxs
-.B \-i
-[
-.BI \-S " name=value
-]
-[
-.BI \-n " modname"
-]
-[
-.B \-a
-]
-[
-.B \-A
-]
-.IR dsofile " ..."
-
-.B apxs
-.B \-e
-[
-.BI \-S " name=value
-]
-[
-.BI \-n " modname"
-]
-[
-.B \-a
-]
-[
-.B \-A
-]
-.IR dsofile " ..."
+.SH "SYNOPSIS"
+
.PP
-.SH DESCRIPTION
-.B 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
-.I files
-which then can be loaded into
-the Apache server under runtime via the
-.B LoadModule
-directive from
-.BR mod_so.
-
-So to use this extension mechanism your platform has
-to support the DSO feature and your
-Apache
-.B httpd
-binary has to be built with the
-.B mod_so
-module.
-The
-.B apxs
-tool automatically complains if this is not the case.
-You can check this yourself by manually running the command
-
-.nf
- $ httpd -l
-.fi
-
-The module
-.B mod_so
-should be part of the displayed list.
-If these requirements are fulfilled you can easily extend
-your Apache server's functionality by installing your own
-modules with the DSO mechanism by the help of this
-.B apxs
-tool:
-
-.nf
- $ apxs -i -a -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
- 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
- $ _
-.fi
-
-The arguments
-.I files
-can be any C source file (.c), a object file (.o) or
-even a library archive (.a). The
-.B apxs
-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
-.BR -fpic .
-For other
-C compilers consult its manual
-page or at watch for the flags
-.B apxs
-uses to compile the object files.
-
-For more details about DSO support in Apache read the documentation
-of
-.B mod_so
-or perhaps even read the
-.B src/modules/standard/mod_so.c
-source file.
+\fBapxs\fR -\fBg\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] -\fBn\fR \fImodname\fR
+
+.PP
+\fBapxs\fR -\fBq\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] \fIquery\fR \&.\&.\&.
+
+.PP
+\fBapxs\fR -\fBc\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBo\fR \fIdsofile\fR ] [ -\fBI\fR \fIincdir\fR ] [ -\fBD\fR \fIname\fR=\fIvalue\fR ] [ -\fBL\fR \fIlibdir\fR ] [ -\fBl\fR \fIlibname\fR ] [ -\fBWc,\fR\fIcompiler-flags\fR ] [ -\fBWl,\fR\fIlinker-flags\fR ] \fIfiles\fR \&.\&.\&.
+
+.PP
+\fBapxs\fR -\fBi\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
+
+.PP
+\fBapxs\fR -\fBe\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
+
+.SH "SUMMARY"
+
.PP
-.SH OPTIONS
-Common options:
-.TP 12
-.BI \-n " modname"
-This explicitly sets the module name for the
-.B \-i
-(install)
-and
-.B \-g
-(template generation) option. Use this to explicitly specify the module name.
-For option
-.B \-g
-this is required, for option
-.B \-i
-the
-.B apxs
-tool tries to determine the name from the source or (as a fallback) at least
-by guessing it from the filename.
+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 \fIfiles\fR which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so\&.
+
.PP
-Query options:
-.TP 12
-.B \-q
-Performs a query for
-.BR apxs 's
-knowledge about certain settings. The
-.I query
-parameters can be one or more of the following strings:
+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
+
.nf
- CC TARGET
- CFLAGS SBINDIR
- CFLAGS_SHLIB INCLUDEDIR
- LD_SHLIB LIBEXECDIR
- LDFLAGS_SHLIB SYSCONFDIR
- LIBS_SHLIB
+
+ $ httpd -l
+
.fi
-Use this for manually determining settings. For instance use
+
+.PP
+The module mod_so should be part of the displayed list\&. If these requirements are fulfilled you can easily extend your Apache server's functionality by installing your own modules with the DSO mechanism by the help of this apxs tool:
+
.nf
- INC=-I`apxs -q INCLUDEDIR`
+
+ $ apxs -i -a -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
+ 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
+ $ _
+
.fi
-inside your own Makefiles if you need manual access
-to Apache's C header files.
-.PP
-Configuration options:
-.TP 12
-.BI \-S " name=value"
-This option changes the apxs settings described above.
+
.PP
-Template Generation options:
-.TP 12
-.B \-g
-This generates a subdirectory
-.I name
-(see option
-.BR \-n ")"
-and there two files: A sample module source file named
-.BI 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
-.B Makefile
-for even easier build and installing of this module.
+The arguments \fIfiles\fR 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 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 -fpic\&. For other C compilers consult its manual page or at watch for the flags apxs uses to compile the object files\&.
+
.PP
-DSO compilation options:
-.TP 12
-.B \-c
-This indicates the compilation operation. It first compiles the C source
-files (.c) of
-.I files
-into corresponding object files (.o) and then builds a dynamically shared object in
-.I dsofile
-by linking these object files plus the remaining
-object files (.o and .a) of
-.I files
-If no
-.B \-o
-option is specified
-the output file is guessed from the first filename in
-.I files
-and thus usually defaults to
-.BI mod_ name.so
-.TP 12
-.BI \-o " dsofile"
-Explicitly specifies the filename of the created dynamically shared object. If
-not specified and the name cannot be guessed from the
-.I files
-list, the fallback name
-.B mod_unknown.so
-is used.
-.TP 12
-.BI \-D " name=value"
-This option is directly passed through to the compilation command(s).
-Use this to add your own defines to the build process.
-.TP 12
-.BI \-I " incdir"
-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.
-.TP 12
-.BI \-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.
-.TP 12
-.BI \-l " libname"
-This option is directly passed through to the linker command.
-Use this to add your own libraries to search to the build process.
-.TP 12
-.BI \-Wc, "compiler-flags"
-This option passes
-.I compiler-flags
-as additional flags to the compiler command.
-Use this to add local compiler-specific options.
-.TP 12
-.BI \-Wl, "linker-flags"
-This option passes
-.I linker-flags
-as additional flags to the linker command.
-Use this to add local linker-specific options.
-.PP
-DSO installation and configuration options:
-.TP 12
-.B \-i
-This indicates the installation operation and installs one or more
-dynamically shared objects into the
-server's
-.I modules
-directory.
-.TP 12
-.B \-a
-This activates the module by automatically adding a corresponding
-.B LoadModule
-line to Apache's
-.B httpd.conf
-configuration file, or by enabling it if it already exists.
-.TP 12
-.B \-A
-Same as option
-.B \-a
-but the created
-.B LoadModule
-directive is prefixed with a hash sign (#), i.e. the module is
-just prepared for later activation but initially disabled.
-.TP 12
-.B \-e
-This indicates the editing operation, which can be used with the
-.B \-a
-and
-.B \-A
-options similarly to the
-.B \-i
-operation to edit Apache's
-.B httpd.conf
-configuration file without attempting to install the module.
-.PD
-.SH EXAMPLES
-Assume you have an Apache module named mod_foo.c available which should extend
-Apache's 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:
+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\&.
+
+.SH "OPTIONS"
+
+.Sh "COMMON OPTIONS"
+
+.RS
+
+.TP
+-n \fImodname\fR
+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\&.
+.RE
+
+.Sh "QUERY OPTIONS"
+
+.RS
+
+.TP
+-q
+Performs a query for apxs's knowledge about certain settings\&. The \fIquery\fR parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET\&. .PP Use this for manually determining settings\&. For instance use .nf INC=-I`apxs -q INCLUDEDIR` .fi .PP inside your own Makefiles if you need manual access to Apache's C header files\&.
+.RE
+
+.Sh "CONFIGURATION OPTIONS"
+
+.RS
+
+.TP
+-S \fIname\fR=\fIvalue\fR
+This option changes the apxs settings described above\&.
+.RE
+
+.Sh "TEMPLATE GENERATION OPTIONS"
+
+.RS
+
+.TP
+-g
+This generates a subdirectory \fIname\fR (see option -n) and there two files: A sample module source file named mod_\fIname\fR\&.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\&.
+.RE
+
+.Sh "DSO COMPILATION OPTIONS"
+
+.RS
+
+.TP
+-c
+This indicates the compilation operation\&. It first compiles the C source files (\&.c) of \fIfiles\fR into corresponding object files (\&.o) and then builds a dynamically shared object in \fIdsofile\fR by linking these object files plus the remaining object files (\&.o and \&.a) of \fIfiles\fR\&. If no -o option is specified the output file is guessed from the first filename in \fIfiles\fR and thus usually defaults to mod_\fIname\fR\&.so\&.
+.TP
+-o \fIdsofile\fR
+Explicitly specifies the filename of the created dynamically shared object\&. If not specified and the name cannot be guessed from the \fIfiles\fR list, the fallback name mod_unknown\&.so is used\&.
+.TP
+-D \fIname\fR=\fIvalue\fR
+This option is directly passed through to the compilation command(s)\&. Use this to add your own defines to the build process\&.
+.TP
+-I \fIincdir\fR
+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\&.
+.TP
+-L \fIlibdir\fR
+This option is directly passed through to the linker command\&. Use this to add your own library directories to search to the build process\&.
+.TP
+-l \fIlibname\fR
+This option is directly passed through to the linker command\&. Use this to add your own libraries to search to the build process\&.
+.TP
+-Wc,\fIcompiler-flags\fR
+This option passes \fIcompiler-flags\fR as additional flags to the compiler command\&. Use this to add local compiler-specific options\&.
+.TP
+-Wl,\fIlinker-flags\fR
+This option passes \fIlinker-flags\fR as additional flags to the linker command\&. Use this to add local linker-specific options\&.
+.RE
+
+.Sh "DSO INSTALLATION AND CONFIGURATION OPTIONS"
+
+.RS
+
+.TP
+-i
+This indicates the installation operation and installs one or more dynamically shared objects into the server's \fImodules\fR directory\&.
+.TP
+-a
+This activates the module by automatically adding a corresponding LoadModule line to Apache's httpd\&.conf configuration file, or by enabling it if it already exists\&.
+.TP
+-A
+Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), \fIi\&.e\&.\fR, the module is just prepared for later activation but initially disabled\&.
+.TP
+-e
+This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit Apache's httpd\&.conf configuration file without attempting to install the module\&.
+.RE
+
+.SH "EXAMPLES"
+
+.PP
+Assume you have an Apache module named mod_foo\&.c available which should extend Apache's 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:
+
.nf
- $ 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
- $ _
-.fi
-Then you have to update the Apache configuration by making sure a
-.B LoadModule
-directive is present to load this shared object. To simplify this
-step
-.B apxs
-provides an automatic way to install the shared object in its
-"modules" directory and updating the
-.B httpd.conf
-file accordingly. This can be achieved by running:
-
-.nf
- $ 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]
- $ _
+ $ 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
+ $ _
+
.fi
+
+.PP
+Then you have to update the Apache configuration by making sure a LoadModule 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 accordingly\&. This can be achieved by running:
+
+.nf
+ $ 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]
+ $ _
+
+.fi
+
+.PP
This way a line named
-
+
.nf
- LoadModule foo_module modules/mod_foo.so
-.fi
-
-is added to the configuration file if still not present.
-If you want to have this disabled per default use the
-.B \-A
-option, i.e.
-.nf
- $ apxs -i -A mod_foo.c
+ LoadModule foo_module modules/mod_foo\&.so
+
.fi
-
-For a quick test of the APXS mechanism you can create a sample Apache module
-template plus a corresponding Makefile via:
-
+
+.PP
+is added to the configuration file if still not present\&. If you want to have this disabled per default use the -A option, \fIi\&.e\&.\fR
+
.nf
- $ apxs -g -n foo
- Creating [DIR] foo
- Creating [FILE] foo/Makefile
- Creating [FILE] foo/mod_foo.c
- $ _
-.fi
-Then you can immediately compile this sample module into a shared object and
-load it into the Apache server:
-
-.nf
- $ 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
- $ _
+ $ apxs -i -A mod_foo\&.c
+
.fi
-
-You can even use
-.B apxs
-to compile complex modules outside the Apache source tree, like PHP3:
-
+
+.PP
+For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:
+
.nf
- $ 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
- $ _
+
+ $ apxs -g -n foo
+ Creating [DIR] foo
+ Creating [FILE] foo/Makefile
+ Creating [FILE] foo/mod_foo\&.c
+ $ _
+
.fi
+
+.PP
+Then you can immediately compile this sample module into a shared object and load it into the Apache server:
+
+.nf
-because
-.B apxs
-automatically recognized C source files and object files. Only C source files
-are compiled while remaining object files are used for the linking phase.
+ $ 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
+ $ _
+
+.fi
+
+.PP
+You can even use apxs to compile complex modules outside the Apache source tree, like PHP3:
+
+.nf
-.PD
-.SH SEE ALSO
-.BR apachectl(1),
-.BR httpd(8).
-.
+ $ 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
+ $ _
+
+.fi
+
+.PP
+because apxs automatically recognized C source files and object files\&. Only C source files are compiled while remaining object files are used for the linking phase\&.
+
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org" />
-
- <title>Manual Page: apxs - Apache HTTP Server</title>
- </head>
-
- <body bgcolor="#ffffff" text="#000000" link="#0000ff"
- vlink="#000080" alink="#ff0000">
- <div align="center">
- <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
-
- <h3>Apache HTTP Server Version 2.1</h3>
- </div>
-
-
-
- <h1 align="center">Manual Page: apxs</h1>
- <!-- This document was autogenerated from the man page -->
-<pre>
-<strong>NAME</strong>
- apxs - APache eXtenSion tool
-
-<strong>SYNOPSIS</strong>
- <strong>apxs</strong> -<strong>g</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] -<strong>n</strong> <em>modname</em>
-
- <strong>apxs</strong> -<strong>q</strong> [ -<strong>S</strong> <em>name</em>=<em>value</em> ] <em>query</em> ...
-
- <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>
- <em>name</em>=<em>value</em> ] [ -<strong>L</strong> <em>libdir</em> ] [ -<strong>l</strong> <em>libname</em> ] [ -<strong>Wc,</strong><em>compiler</em>-
- <em>flags</em> ] [ -<strong>Wl,</strong><em>linker</em>-<em>flags</em> ] <em>files</em> ...
-
- <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>
- <em>file</em> ...
-
- <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>
- <em>file</em> ...
-
-<strong>DESCRIPTION</strong>
- <strong>apxs</strong> 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 <em>files</em> which then can be
- loaded into the Apache server under runtime via the <strong>LoadMo-</strong>
- <strong>dule</strong> directive from <strong>mod_so.</strong>
-
- So to use this extension mechanism your platform has to sup-
- port the DSO feature and your Apache <strong>httpd</strong> binary has to be
- built with the <strong>mod_so</strong> module. The <strong>apxs</strong> tool automatically
- complains if this is not the case. You can check this your-
- self by manually running the command
-
- $ httpd -l
-
- The module <strong>mod_so</strong> should be part of the displayed list. If
- these requirements are fulfilled you can easily extend your
- Apache server's functionality by installing your own modules
- with the DSO mechanism by the help of this <strong>apxs</strong> tool:
-
- $ apxs -i -a -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
- 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>
-
--- /dev/null
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>apxs - APache eXtenSion tool - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.1</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Programs</a></div><div id="page-content"><div id="preamble"><h1>apxs - APache eXtenSion tool</h1>
+ <p><code>apxs</code> 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 <var>files</var> which then can be loaded into the Apache server
+ under runtime via the <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>
+ directive from <code class="module"><a href="../mod/mod_so.html">mod_so</a></code>.</p>
+
+ <p>So to use this extension mechanism your platform has to support the DSO
+ feature and your Apache <code>httpd</code> binary has to be built with the
+ <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> module. The <code>apxs</code> tool automatically
+ complains if this is not the case. You can check this yourself by manually
+ running the command</p>
+
+ <div class="example"><p><code>
+ $ httpd -l
+ </code></p></div>
+
+ <p>The module <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> should be part of the displayed list.
+ If these requirements are fulfilled you can easily extend your Apache
+ server's functionality by installing your own modules with the DSO mechanism
+ by the help of this <code>apxs</code> tool:</p>
+
+ <div class="example"><p><code>
+ $ apxs -i -a -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ $ apachectl restart<br />
+ /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
+ [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
+ /path/to/apache/sbin/apachectl restart: httpd started<br />
+ $ _
+ </code></p></div>
+
+ <p>The arguments <var>files</var> can be any C source file (.c), a object
+ file (.o) or even a library archive (.a). The <code>apxs</code> 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 <code>-fpic</code>. For other C compilers consult its
+ manual page or at watch for the flags <code>apxs</code> uses to compile the
+ object files.</p>
+
+ <p>For more details about DSO support in Apache read the documentation of
+ <code class="module"><a href="../mod/mod_so.html">mod_so</a></code> or perhaps even read the
+ <code>src/modules/standard/mod_so.c</code> source file.</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#synopsis">Synopsis</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="apachectl.html">apachectl</a></li><li><a href="httpd.html">httpd</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="synopsis" id="synopsis">Synopsis</a></h2>
+ <p><code><strong>apxs</strong> -<strong>g</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ -<strong>n</strong> <var>modname</var></code></p>
+
+ <p><code><strong>apxs</strong> -<strong>q</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ <var>query</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>c</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>o</strong> <var>dsofile</var> ]
+ [ -<strong>I</strong> <var>incdir</var> ]
+ [ -<strong>D</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>L</strong> <var>libdir</var> ]
+ [ -<strong>l</strong> <var>libname</var> ]
+ [ -<strong>Wc,</strong><var>compiler-flags</var> ]
+ [ -<strong>Wl,</strong><var>linker-flags</var> ]
+ <var>files</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>i</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>n</strong> <var>modname</var> ]
+ [ -<strong>a</strong> ]
+ [ -<strong>A</strong> ]
+ <var>dso-file</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>e</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>n</strong> <var>modname</var> ]
+ [ -<strong>a</strong> ]
+ [ -<strong>A</strong> ]
+ <var>dso-file</var> ...</code></p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="options" id="options">Options</a></h2>
+ <h3><a name="options.common" id="options.common">Common Options</a></h3>
+ <dl>
+ <dt><code>-n <var>modname</var></code></dt>
+ <dd>This explicitly sets the module name for the <code>-i</code> (install)
+ and <code>-g</code> (template generation) option. Use this to explicitly
+ specify the module name. For option <code>-g</code> this is required, for
+ option <code>-i</code> the <code>apxs</code> tool tries to determine the
+ name from the source or (as a fallback) at least by guessing it from the
+ filename.</dd>
+ </dl>
+
+
+ <h3><a name="options.query" id="options.query">Query Options</a></h3>
+ <dl>
+ <dt><code>-q</code></dt>
+ <dd>Performs a query for <code>apxs</code>'s knowledge about certain
+ settings. The <var>query</var> parameters can be one or more of the
+ following strings: <code>CC</code>, <code>CFLAGS</code>,
+ <code>CFLAGS_SHLIB</code>, <code>INCLUDEDIR</code>, <code>LD_SHLIB</code>,
+ <code>LDFLAGS_SHLIB</code>, <code>LIBEXECDIR</code>,
+ <code>LIBS_SHLIB</code>, <code>SBINDIR</code>, <code>SYSCONFDIR</code>,
+ <code>TARGET</code>.
+
+ <p>Use this for manually determining settings. For instance use</p>
+ <div class="example"><p><code>
+ INC=-I`apxs -q INCLUDEDIR`
+ </code></p></div>
+
+ <p>inside your own Makefiles if you need manual access to Apache's C
+ header files.</p></dd>
+ </dl>
+
+
+ <h3><a name="options.conf" id="options.conf">Configuration Options</a></h3>
+ <dl>
+ <dt><code>-S <var>name</var>=<var>value</var></code></dt>
+ <dd>This option changes the apxs settings described above.</dd>
+ </dl>
+
+
+ <h3><a name="options.template" id="options.template">Template Generation Options</a></h3>
+ <dl>
+ <dt><code>-g</code></dt>
+ <dd>This generates a subdirectory <var>name</var> (see option
+ <code>-n</code>) and there two files: A sample module source file named
+ <code>mod_<var>name</var>.c</code> 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 <code>Makefile</code> for even easier
+ build and installing of this module.</dd>
+ </dl>
+
+
+ <h3><a name="options.dso" id="options.dso">DSO Compilation Options</a></h3>
+ <dl>
+ <dt><code>-c</code></dt>
+ <dd>This indicates the compilation operation. It first compiles the C
+ source files (.c) of <var>files</var> into corresponding object files (.o)
+ and then builds a dynamically shared object in <var>dsofile</var> by
+ linking these object files plus the remaining object files (.o and .a) of
+ <var>files</var>. If no <code>-o</code> option is specified the output
+ file is guessed from the first filename in <var>files</var> and thus
+ usually defaults to <code>mod_<var>name</var>.so</code>.</dd>
+
+ <dt><code>-o <var>dsofile</var></code></dt>
+ <dd>Explicitly specifies the filename of the created dynamically shared
+ object. If not specified and the name cannot be guessed from the
+ <var>files</var> list, the fallback name <code>mod_unknown.so</code> is
+ used.</dd>
+
+ <dt><code>-D <var>name</var>=<var>value</var></code></dt>
+ <dd>This option is directly passed through to the compilation command(s).
+ Use this to add your own defines to the build process.</dd>
+
+ <dt><code>-I <var>incdir</var></code></dt>
+ <dd>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.</dd>
+
+ <dt><code>-L <var>libdir</var></code></dt>
+ <dd>This option is directly passed through to the linker command. Use this
+ to add your own library directories to search to the build process.</dd>
+
+ <dt><code>-l <var>libname</var></code></dt>
+ <dd>This option is directly passed through to the linker command. Use this
+ to add your own libraries to search to the build process.</dd>
+
+ <dt><code>-Wc,<var>compiler-flags</var></code></dt>
+ <dd>This option passes <var>compiler-flags</var> as additional flags to
+ the compiler command. Use this to add local compiler-specific options.</dd>
+
+ <dt><code>-Wl,<var>linker-flags</var></code></dt>
+ <dd>This option passes <var>linker-flags</var> as additional flags to
+ the linker command. Use this to add local linker-specific options.</dd>
+ </dl>
+
+
+ <h3><a name="options.dsoinstall" id="options.dsoinstall">DSO Installation and Configuration Options</a></h3>
+
+ <dl>
+ <dt><code>-i</code></dt>
+ <dd>This indicates the installation operation and installs one or more
+ dynamically shared objects into the server's <var>modules</var>
+ directory.</dd>
+
+ <dt><code>-a</code></dt>
+ <dd>This activates the module by automatically adding a corresponding
+ <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> line to Apache's
+ <code>httpd.conf</code> configuration file, or by enabling it if it
+ already exists.</dd>
+
+ <dt><code>-A</code></dt>
+ <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
+ sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for
+ later activation but initially disabled.</dd>
+
+ <dt><code>-e</code></dt>
+ <dd>This indicates the editing operation, which can be used with the
+ <code>-a</code> and <code>-A</code> options similarly to the
+ <code>-i</code> operation to edit Apache's <code>httpd.conf</code>
+ configuration file without attempting to install the module.</dd>
+ </dl>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+ <p>Assume you have an Apache module named <code>mod_foo.c</code> available
+ which should extend Apache's 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:</p>
+
+ <div class="example"><p><code>
+ $ apxs -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ $ _
+ </code></p></div>
+
+ <p>Then you have to update the Apache configuration by making sure a
+ <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive is present to
+ load this shared object. To simplify this step <code>apxs</code> provides
+ an automatic way to install the shared object in its "modules" directory
+ and updating the <code>httpd.conf</code> file accordingly. This can be
+ achieved by running:</p>
+
+ <div class="example"><p><code>
+ $ apxs -i -a mod_foo.c<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ $ _
+ </code></p></div>
+
+ <p>This way a line named</p>
+
+ <div class="example"><p><code>
+ LoadModule foo_module modules/mod_foo.so
+ </code></p></div>
+
+ <p>is added to the configuration file if still not present. If you want to
+ have this disabled per default use the <code>-A</code> option,
+ <em>i.e.</em></p>
+
+ <div class="example"><p><code>
+ $ apxs -i -A mod_foo.c
+ </code></p></div>
+
+ <p>For a quick test of the apxs mechanism you can create a sample Apache
+ module template plus a corresponding Makefile via:</p>
+
+ <div class="example"><p><code>
+ $ apxs -g -n foo<br />
+ Creating [DIR] foo<br />
+ Creating [FILE] foo/Makefile<br />
+ Creating [FILE] foo/mod_foo.c<br />
+ $ _
+ </code></p></div>
+
+ <p>Then you can immediately compile this sample module into a shared object
+ and load it into the Apache server:</p>
+
+ <div class="example"><p><code>
+ $ cd foo<br />
+ $ make all reload<br />
+ apxs -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ apxs -i -a -n "foo" mod_foo.so<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ apachectl restart<br />
+ /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
+ [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
+ /path/to/apache/sbin/apachectl restart: httpd started<br />
+ $ _
+ </code></p></div>
+
+ <p>You can even use <code>apxs</code> to compile complex modules outside the
+ Apache source tree, like PHP3:</p>
+
+ <div class="example"><p><code>
+ $ cd php3<br />
+ $ ./configure --with-shared-apache=../apache-1.3<br />
+ $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a<br />
+ gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c<br />
+ ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a<br />
+ $ _
+ </code></p></div>
+
+ <p>because <code>apxs</code> automatically recognized C source files and
+ object files. Only C source files are compiled while remaining object
+ files are used for the linking phase.</p>
+</div></div>
+<div id="footer">
+<p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file
--- /dev/null
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<manualpage metafile="apxs.xml.meta">
+<parentdocument href="./">Programs</parentdocument>
+
+<title>apxs - APache eXtenSion tool</title>
+
+<summary>
+ <p><code>apxs</code> 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 <var>files</var> which then can be loaded into the Apache server
+ under runtime via the <directive module="mod_so">LoadModule</directive>
+ directive from <module>mod_so</module>.</p>
+
+ <p>So to use this extension mechanism your platform has to support the DSO
+ feature and your Apache <code>httpd</code> binary has to be built with the
+ <module>mod_so</module> module. The <code>apxs</code> tool automatically
+ complains if this is not the case. You can check this yourself by manually
+ running the command</p>
+
+ <example>
+ $ httpd -l
+ </example>
+
+ <p>The module <module>mod_so</module> should be part of the displayed list.
+ If these requirements are fulfilled you can easily extend your Apache
+ server's functionality by installing your own modules with the DSO mechanism
+ by the help of this <code>apxs</code> tool:</p>
+
+ <example>
+ $ apxs -i -a -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ $ apachectl restart<br />
+ /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
+ [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
+ /path/to/apache/sbin/apachectl restart: httpd started<br />
+ $ _
+ </example>
+
+ <p>The arguments <var>files</var> can be any C source file (.c), a object
+ file (.o) or even a library archive (.a). The <code>apxs</code> 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 <code>-fpic</code>. For other C compilers consult its
+ manual page or at watch for the flags <code>apxs</code> uses to compile the
+ object files.</p>
+
+ <p>For more details about DSO support in Apache read the documentation of
+ <module>mod_so</module> or perhaps even read the
+ <code>src/modules/standard/mod_so.c</code> source file.</p>
+</summary>
+<seealso><a href="apachectl.html">apachectl</a></seealso>
+<seealso><a href="httpd.html">httpd</a></seealso>
+
+<section id="synopsis"><title>Synopsis</title>
+ <p><code><strong>apxs</strong> -<strong>g</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ -<strong>n</strong> <var>modname</var></code></p>
+
+ <p><code><strong>apxs</strong> -<strong>q</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ <var>query</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>c</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>o</strong> <var>dsofile</var> ]
+ [ -<strong>I</strong> <var>incdir</var> ]
+ [ -<strong>D</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>L</strong> <var>libdir</var> ]
+ [ -<strong>l</strong> <var>libname</var> ]
+ [ -<strong>Wc,</strong><var>compiler-flags</var> ]
+ [ -<strong>Wl,</strong><var>linker-flags</var> ]
+ <var>files</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>i</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>n</strong> <var>modname</var> ]
+ [ -<strong>a</strong> ]
+ [ -<strong>A</strong> ]
+ <var>dso-file</var> ...</code></p>
+
+ <p><code><strong>apxs</strong> -<strong>e</strong>
+ [ -<strong>S</strong> <var>name</var>=<var>value</var> ]
+ [ -<strong>n</strong> <var>modname</var> ]
+ [ -<strong>a</strong> ]
+ [ -<strong>A</strong> ]
+ <var>dso-file</var> ...</code></p>
+</section>
+
+<section id="options"><title>Options</title>
+ <section id="options.common"><title>Common Options</title>
+ <dl>
+ <dt><code>-n <var>modname</var></code></dt>
+ <dd>This explicitly sets the module name for the <code>-i</code> (install)
+ and <code>-g</code> (template generation) option. Use this to explicitly
+ specify the module name. For option <code>-g</code> this is required, for
+ option <code>-i</code> the <code>apxs</code> tool tries to determine the
+ name from the source or (as a fallback) at least by guessing it from the
+ filename.</dd>
+ </dl>
+ </section>
+
+ <section id="options.query"><title>Query Options</title>
+ <dl>
+ <dt><code>-q</code></dt>
+ <dd>Performs a query for <code>apxs</code>'s knowledge about certain
+ settings. The <var>query</var> parameters can be one or more of the
+ following strings: <code>CC</code>, <code>CFLAGS</code>,
+ <code>CFLAGS_SHLIB</code>, <code>INCLUDEDIR</code>, <code>LD_SHLIB</code>,
+ <code>LDFLAGS_SHLIB</code>, <code>LIBEXECDIR</code>,
+ <code>LIBS_SHLIB</code>, <code>SBINDIR</code>, <code>SYSCONFDIR</code>,
+ <code>TARGET</code>.
+
+ <p>Use this for manually determining settings. For instance use</p>
+ <example>
+ INC=-I`apxs -q INCLUDEDIR`
+ </example>
+
+ <p>inside your own Makefiles if you need manual access to Apache's C
+ header files.</p></dd>
+ </dl>
+ </section>
+
+ <section id="options.conf"><title>Configuration Options</title>
+ <dl>
+ <dt><code>-S <var>name</var>=<var>value</var></code></dt>
+ <dd>This option changes the apxs settings described above.</dd>
+ </dl>
+ </section>
+
+ <section id="options.template"><title>Template Generation Options</title>
+ <dl>
+ <dt><code>-g</code></dt>
+ <dd>This generates a subdirectory <var>name</var> (see option
+ <code>-n</code>) and there two files: A sample module source file named
+ <code>mod_<var>name</var>.c</code> 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 <code>Makefile</code> for even easier
+ build and installing of this module.</dd>
+ </dl>
+ </section>
+
+ <section id="options.dso"><title>DSO Compilation Options</title>
+ <dl>
+ <dt><code>-c</code></dt>
+ <dd>This indicates the compilation operation. It first compiles the C
+ source files (.c) of <var>files</var> into corresponding object files (.o)
+ and then builds a dynamically shared object in <var>dsofile</var> by
+ linking these object files plus the remaining object files (.o and .a) of
+ <var>files</var>. If no <code>-o</code> option is specified the output
+ file is guessed from the first filename in <var>files</var> and thus
+ usually defaults to <code>mod_<var>name</var>.so</code>.</dd>
+
+ <dt><code>-o <var>dsofile</var></code></dt>
+ <dd>Explicitly specifies the filename of the created dynamically shared
+ object. If not specified and the name cannot be guessed from the
+ <var>files</var> list, the fallback name <code>mod_unknown.so</code> is
+ used.</dd>
+
+ <dt><code>-D <var>name</var>=<var>value</var></code></dt>
+ <dd>This option is directly passed through to the compilation command(s).
+ Use this to add your own defines to the build process.</dd>
+
+ <dt><code>-I <var>incdir</var></code></dt>
+ <dd>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.</dd>
+
+ <dt><code>-L <var>libdir</var></code></dt>
+ <dd>This option is directly passed through to the linker command. Use this
+ to add your own library directories to search to the build process.</dd>
+
+ <dt><code>-l <var>libname</var></code></dt>
+ <dd>This option is directly passed through to the linker command. Use this
+ to add your own libraries to search to the build process.</dd>
+
+ <dt><code>-Wc,<var>compiler-flags</var></code></dt>
+ <dd>This option passes <var>compiler-flags</var> as additional flags to
+ the compiler command. Use this to add local compiler-specific options.</dd>
+
+ <dt><code>-Wl,<var>linker-flags</var></code></dt>
+ <dd>This option passes <var>linker-flags</var> as additional flags to
+ the linker command. Use this to add local linker-specific options.</dd>
+ </dl>
+ </section>
+
+ <section id="options.dsoinstall">
+ <title>DSO Installation and Configuration Options</title>
+ <dl>
+ <dt><code>-i</code></dt>
+ <dd>This indicates the installation operation and installs one or more
+ dynamically shared objects into the server's <var>modules</var>
+ directory.</dd>
+
+ <dt><code>-a</code></dt>
+ <dd>This activates the module by automatically adding a corresponding
+ <directive module="mod_so">LoadModule</directive> line to Apache's
+ <code>httpd.conf</code> configuration file, or by enabling it if it
+ already exists.</dd>
+
+ <dt><code>-A</code></dt>
+ <dd>Same as option <code>-a</code> but the created <directive
+ module="mod_so">LoadModule</directive> directive is prefixed with a hash
+ sign (<code>#</code>), <em>i.e.</em>, the module is just prepared for
+ later activation but initially disabled.</dd>
+
+ <dt><code>-e</code></dt>
+ <dd>This indicates the editing operation, which can be used with the
+ <code>-a</code> and <code>-A</code> options similarly to the
+ <code>-i</code> operation to edit Apache's <code>httpd.conf</code>
+ configuration file without attempting to install the module.</dd>
+ </dl>
+ </section>
+</section>
+
+<section id="examples"><title>Examples</title>
+ <p>Assume you have an Apache module named <code>mod_foo.c</code> available
+ which should extend Apache's 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:</p>
+
+ <example>
+ $ apxs -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ $ _
+ </example>
+
+ <p>Then you have to update the Apache configuration by making sure a
+ <directive module="mod_so">LoadModule</directive> directive is present to
+ load this shared object. To simplify this step <code>apxs</code> provides
+ an automatic way to install the shared object in its "modules" directory
+ and updating the <code>httpd.conf</code> file accordingly. This can be
+ achieved by running:</p>
+
+ <example>
+ $ apxs -i -a mod_foo.c<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ $ _
+ </example>
+
+ <p>This way a line named</p>
+
+ <example>
+ LoadModule foo_module modules/mod_foo.so
+ </example>
+
+ <p>is added to the configuration file if still not present. If you want to
+ have this disabled per default use the <code>-A</code> option,
+ <em>i.e.</em></p>
+
+ <example>
+ $ apxs -i -A mod_foo.c
+ </example>
+
+ <p>For a quick test of the apxs mechanism you can create a sample Apache
+ module template plus a corresponding Makefile via:</p>
+
+ <example>
+ $ apxs -g -n foo<br />
+ Creating [DIR] foo<br />
+ Creating [FILE] foo/Makefile<br />
+ Creating [FILE] foo/mod_foo.c<br />
+ $ _
+ </example>
+
+ <p>Then you can immediately compile this sample module into a shared object
+ and load it into the Apache server:</p>
+
+ <example>
+ $ cd foo<br />
+ $ make all reload<br />
+ apxs -c mod_foo.c<br />
+ gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c<br />
+ ld -Bshareable -o mod_foo.so mod_foo.o<br />
+ apxs -i -a -n "foo" mod_foo.so<br />
+ cp mod_foo.so /path/to/apache/modules/mod_foo.so<br />
+ chmod 755 /path/to/apache/modules/mod_foo.so<br />
+ [activating module `foo' in /path/to/apache/etc/httpd.conf]<br />
+ apachectl restart<br />
+ /path/to/apache/sbin/apachectl restart: httpd not running, trying to start<br />
+ [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module<br />
+ /path/to/apache/sbin/apachectl restart: httpd started<br />
+ $ _
+ </example>
+
+ <p>You can even use <code>apxs</code> to compile complex modules outside the
+ Apache source tree, like PHP3:</p>
+
+ <example>
+ $ cd php3<br />
+ $ ./configure --with-shared-apache=../apache-1.3<br />
+ $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a<br />
+ gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c<br />
+ ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a<br />
+ $ _
+ </example>
+
+ <p>because <code>apxs</code> automatically recognized C source files and
+ object files. Only C source files are compiled while remaining object
+ files are used for the linking phase.</p>
+</section>
+</manualpage>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+ <basename>apxs</basename>
+ <path>/programs/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
<!-- documents not converted (yet?). -->
<not-exists>
<file>developer/API.xml</file>
- <file>programs/apxs.xml</file>
<file>programs/dbmmanage.xml</file>
<file>programs/htdigest.xml</file>
<file>programs/htpasswd.xml</file>
<!-- /section -->
+<!-- ==================================================================== -->
+<!-- <section><section> -->
+<!-- process subsection -->
+<!-- ==================================================================== -->
+<xsl:template match="section/section">
+&lf;
+<xsl:text>.Sh "</xsl:text>
+ <xsl:call-template name="filter.escape">
+ <xsl:with-param name="text"
+ select="normalize-space(translate(title, $lowercase, $uppercase))"/>
+ </xsl:call-template>
+<xsl:text>"</xsl:text>&lf;
+<xsl:apply-templates />
+</xsl:template>
+<!-- /section/section -->
+
+
<!-- ==================================================================== -->
<!-- <summary> -->
<!-- process summary section -->
projects / apache / commitdiff