diff options
Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/programs/apxs.html')
| -rw-r--r-- | usr.sbin/httpd/htdocs/manual/programs/apxs.html | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/programs/apxs.html b/usr.sbin/httpd/htdocs/manual/programs/apxs.html new file mode 100644 index 00000000000..f0b3aa32666 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/programs/apxs.html @@ -0,0 +1,297 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> + <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 1.3 + </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>variable</em>=<em>value </em>] -<strong>n </strong><em>name</em> + + <strong>apxs </strong>-<strong>q </strong>[ -<strong>S </strong><em>variable</em>=<em>value </em>] <em>query </em>... + + <strong>apxs </strong>-<strong>c </strong>[ -<strong>S </strong><em>variable</em>=<em>value </em>] [ -<strong>o </strong><em>dsofile </em>] [ -<strong>I </strong><em>incdir </em>] [ + -<strong>D </strong><em>variable</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>variable</em>=<em>value </em>] [ -<strong>n </strong><em>name </em>] [ -<strong>a </strong>] [ -<strong>A </strong>] <em>dso-</em> + <em>file </em>... + + <strong>apxs </strong>-<strong>e </strong>[ -<strong>S </strong><em>variable</em>=<em>value </em>] [ -<strong>n </strong><em>name </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 + support 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 automati- + cally complains if this is not the case. You can check this + yourself 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/libexec/mod_foo.so + chmod 755 /path/to/apache/libexec/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 + uses the C source files for compilation while it just uses + 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 DSO. For instance with GCC you always just have to use + <strong>-fpic</strong>. For other C compilers please consult its manual page + or watch for the flags <strong>apxs </strong>uses to compile the object + files. + + For more details about DSO support in Apache, first read the + background information about DSO in htdocs/manual/dso.html, + then read the documentation of <strong>mod_so</strong>. + +<strong>OPTIONS</strong> + Common options: + + -<strong>n </strong><em>name </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 variable names: + CC TARGET + CFLAGS SBINDIR + CFLAGS_SHLIB INCLUDEDIR + LD_SHLIB LIBEXECDIR + LDFLAGS_SHLIB SYSCONFDIR + LIBS_SHLIB PREFIX + 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>variable</em>=<em>value</em> + This option changes the <strong>apxs </strong>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 <strong>apxs </strong>mechanism. + And a corresponding <strong>Makefile </strong>for even easier + building 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 DSO 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 usually defaults to + <strong>mod_</strong><em>name</em>.<em>so</em> + + -<strong>o </strong><em>dsofile </em>Explicitly specifies the filename of the created + DSO file. 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>variable</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 DSOs into the server's + <em>libexec </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 DSO + 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 DSO. To + simplify this step <strong>apxs </strong>provides an automatic way to install + the DSO in the "libexec" directory and updating the + <strong>httpd.conf </strong>file accordingly. This can be achieved by run- + ning: + + $ apxs -i -a mod_foo.c + cp mod_foo.so /path/to/apache/libexec/mod_foo.so + chmod 755 /path/to/apache/libexec/mod_foo.so + [activating module `foo' in /path/to/apache/etc/httpd.conf] + $ _ + + This way a line named + + LoadModule foo_module libexec/mod_foo.so + + is added to the configuration file if still not present. If + you want to have this operation to be disabled, use the -<strong>A</strong> + option, i.e. + + $ apxs -i -A mod_foo.c + + For a quick test of the <strong>apxs </strong>mechanism you can create a sam- + ple Apache module template plus a corresponding <strong>Makefile</strong> + 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 + DSO 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/libexec/mod_foo.so + chmod 755 /path/to/apache/libexec/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, because <strong>apxs </strong>automatically + recognized C source files and object files. + + $ 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 + $ _ + + 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 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body></html> |