From: André Malo Date: Tue, 29 Apr 2003 23:07:54 +0000 (+0000) Subject: new XML X-Git-Tag: pre_ajp_proxy~1756 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=bc1a0d68814ad2d7eaf287dd7a0a5ffda47d52e3;p=apache new XML git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@99652 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/STATUS b/docs/STATUS index 4ffd274606..ccd44b8710 100644 --- a/docs/STATUS +++ b/docs/STATUS @@ -1,5 +1,5 @@ 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/ @@ -189,10 +189,7 @@ http://httpd.apache.org/docs-project/docsformat.html 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 diff --git a/docs/man/apxs.8 b/docs/man/apxs.8 index 0bb36af8b2..e8cf0667f6 100644 --- a/docs/man/apxs.8 +++ b/docs/man/apxs.8 @@ -1,458 +1,267 @@ -.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 -.\" . -.\" +.\" 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\&. + diff --git a/docs/manual/programs/apxs.html b/docs/manual/programs/apxs.html deleted file mode 100644 index 9a6b251c48..0000000000 --- a/docs/manual/programs/apxs.html +++ /dev/null @@ -1,293 +0,0 @@ - - - - - - - Manual Page: apxs - Apache HTTP Server - - - -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 2.1

-
- - - -

Manual Page: apxs

- -
-NAME
-     apxs - APache eXtenSion tool
-
-SYNOPSIS
-     apxs -g [ -S name=value ] -n modname
-
-     apxs -q [ -S name=value ] query ...
-
-     apxs -c [ -S name=value ] [ -o dsofile ] [ -I incdir ] [  -D
-     name=value  ]  [  -L libdir ] [ -l libname ] [ -Wc,compiler-
-     flags ] [ -Wl,linker-flags ] files ...
-
-     apxs -i [ -S name=value ] [ -n modname ] [ -a ] [ -A ]  dso-
-     file ...
-
-     apxs -e [ -S name=value ] [ -n modname ] [ -a ] [ -A ]  dso-
-     file ...
-
-DESCRIPTION
-     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 runtime via the  LoadMo-
-     dule directive from mod_so.
-
-     So to use this extension mechanism your platform has to sup-
-     port  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 your-
-     self 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 server's functionality by installing your own modules
-     with the DSO mechanism by the help of this apxs 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 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 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  com-
-     pilers  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  docu-
-     mentation    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 guess-
-                 ing it from the filename.
-
-     Query options:
-
-     -q          Performs a query for apxs's knowledge about cer-
-                 tain  settings.  The query 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:
-
-     -S name=value
-                 This option changes the apxs settings  described
-                 above.
-
-     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 usu-
-                 ally 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  command(s).   Use  this to add your
-                 own defines to the build process.
-
-     -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.
-
-     -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  pro-
-                 cess.
-
-     -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.
-
-     -Wc,compiler-flags
-                 This option passes compiler-flags as  additional
-                 flags  to the compiler command.  Use this to add
-                 local compiler-specific options.
-
-     -Wl,linker-flags
-                 This option passes  linker-flags  as  additional
-                 flags  to  the  linker command.  Use this to add
-                 local linker-specific options.
-
-     DSO installation and configuration options:
-
-     -i          This indicates the  installation  operation  and
-                 installs  one or more dynamically shared objects
-                 into the server's modules directory.
-
-     -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.
-
-     -A          Same as option -a  but  the  created  LoadModule
-                 directive is prefixed 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  Apache's  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 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  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:
-
-       $ 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 -A
-     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 apxs 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 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.
-
-SEE ALSO
-     apachectl(1), httpd(8).
-
-
-
- -

Apache HTTP Server Version 2.1

- Index - Home - - - - - diff --git a/docs/manual/programs/apxs.html.en b/docs/manual/programs/apxs.html.en new file mode 100644 index 0000000000..e21de9dd80 --- /dev/null +++ b/docs/manual/programs/apxs.html.en @@ -0,0 +1,329 @@ + + + +apxs - APache eXtenSion tool - Apache HTTP Server + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.1

+
+
<-
+

apxs - APache eXtenSion tool

+

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 runtime 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 + server's functionality by installing your own modules with the DSO mechanism + by the help of this apxs 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 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 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.

+ +

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.

+
+ +
top
+
+

Synopsis

+

apxs -g + [ -S name=value ] + -n modname

+ +

apxs -q + [ -S name=value ] + query ...

+ +

apxs -c + [ -S name=value ] + [ -o dsofile ] + [ -I incdir ] + [ -D name=value ] + [ -L libdir ] + [ -l libname ] + [ -Wc,compiler-flags ] + [ -Wl,linker-flags ] + files ...

+ +

apxs -i + [ -S name=value ] + [ -n modname ] + [ -a ] + [ -A ] + dso-file ...

+ +

apxs -e + [ -S name=value ] + [ -n modname ] + [ -a ] + [ -A ] + dso-file ...

+
top
+
+

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, + TARGET. + +

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

+
+
-S name=value
+
This option changes the apxs settings described above.
+
+ + +

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 command(s). + Use this to add your own defines to the build process.
+ +
-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.
+ +
-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 process.
+ +
-Wc,compiler-flags
+
This option passes compiler-flags as additional flags to + the compiler command. Use this to add local compiler-specific options.
+ +
-Wl,linker-flags
+
This option passes linker-flags as additional flags to + the linker command. Use this to add local linker-specific options.
+
+ + +

DSO Installation and Configuration Options

+ +
+
-i
+
This indicates the installation operation and installs one or more + dynamically shared objects into the server's modules + directory.
+ +
-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.
+ +
-A
+
Same as option -a but the created LoadModule directive is prefixed 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 Apache's httpd.conf + configuration file without attempting to install the module.
+
+ +
top
+
+

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:

+ +

+ $ 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 + 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:

+ +

+ $ 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 -A option, + i.e.

+ +

+ $ apxs -i -A mod_foo.c +

+ +

For a quick test of the apxs mechanism you can create a sample 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 apxs 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 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.

+
+ + \ No newline at end of file diff --git a/docs/manual/programs/apxs.xml b/docs/manual/programs/apxs.xml new file mode 100644 index 0000000000..472bf9da7d --- /dev/null +++ b/docs/manual/programs/apxs.xml @@ -0,0 +1,314 @@ + + + + +Programs + +apxs - APache eXtenSion tool + + +

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 runtime 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 + server's functionality by installing your own modules with the DSO mechanism + by the help of this apxs 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 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 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.

+ +

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.

+ +apachectl +httpd + +
Synopsis +

apxs -g + [ -S name=value ] + -n modname

+ +

apxs -q + [ -S name=value ] + query ...

+ +

apxs -c + [ -S name=value ] + [ -o dsofile ] + [ -I incdir ] + [ -D name=value ] + [ -L libdir ] + [ -l libname ] + [ -Wc,compiler-flags ] + [ -Wl,linker-flags ] + files ...

+ +

apxs -i + [ -S name=value ] + [ -n modname ] + [ -a ] + [ -A ] + dso-file ...

+ +

apxs -e + [ -S name=value ] + [ -n modname ] + [ -a ] + [ -A ] + dso-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, + TARGET. + +

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 +
+
-S name=value
+
This option changes the apxs settings described above.
+
+
+ +
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 command(s). + Use this to add your own defines to the build process.
+ +
-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.
+ +
-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 process.
+ +
-Wc,compiler-flags
+
This option passes compiler-flags as additional flags to + the compiler command. Use this to add local compiler-specific options.
+ +
-Wl,linker-flags
+
This option passes linker-flags as additional flags to + the linker command. Use this to add local linker-specific options.
+
+
+ +
+ DSO Installation and Configuration Options +
+
-i
+
This indicates the installation operation and installs one or more + dynamically shared objects into the server's modules + directory.
+ +
-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.
+ +
-A
+
Same as option -a but the created LoadModule directive is prefixed 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 Apache's 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 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:

+ + + $ 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 + 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:

+ + + $ 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 -A option, + i.e.

+ + + $ apxs -i -A mod_foo.c + + +

For a quick test of the apxs mechanism you can create a sample 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 apxs 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 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.

+
+ diff --git a/docs/manual/programs/apxs.xml.meta b/docs/manual/programs/apxs.xml.meta new file mode 100644 index 0000000000..8a4ddfceb0 --- /dev/null +++ b/docs/manual/programs/apxs.xml.meta @@ -0,0 +1,11 @@ + + + + apxs + /programs/ + .. + + + en + + diff --git a/docs/manual/style/chm/hhc.xsl b/docs/manual/style/chm/hhc.xsl index 276c61b3dc..4a085e7d73 100644 --- a/docs/manual/style/chm/hhc.xsl +++ b/docs/manual/style/chm/hhc.xsl @@ -84,7 +84,6 @@ developer/API.xml - programs/apxs.xml programs/dbmmanage.xml programs/htdigest.xml programs/htpasswd.xml diff --git a/docs/manual/style/man/manpage.xsl b/docs/manual/style/man/manpage.xsl index 3a56afa486..54f0430fef 100644 --- a/docs/manual/style/man/manpage.xsl +++ b/docs/manual/style/man/manpage.xsl @@ -251,6 +251,23 @@ + + + + + +&lf; +.Sh " + + + +"&lf; + + + + +