mirror of
https://github.com/apache/httpd.git
synced 2025-10-21 12:13:46 +03:00
f88b50dec4
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91116 13f79535-47bb-0310-9956-ffa450edef68
282 lines
13 KiB
HTML
282 lines
13 KiB
HTML
<!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">
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<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>
|
|
<!--#include virtual="footer.html" -->
|
|
</body>
|
|
</html>
|
|
|