apxs.8(8)
apxs - APache eXtenSion tool
Showing IRIX 6.5.15. Added in IRIX 6.5.15.
NAME apxs - APache eXtenSion tool SYNOPSIS apxs -g [ -S variable=value ] -n name apxs -q [ -S variable=value ] query ... apxs -c [ -S variable=value ] [ -o dsofile ] [ -I incdir ] [ -D vari- able[=value] ] [ -L libdir ] [ -l libname ] [ -Wc,compiler-flags ] [ -Wl,linker-flags ] files ... apxs -i [ -S variable=value ] [ -n name ] [ -a ] [ -A ] dsofile ... apxs -e [ -S variable=value ] [ -n name ] [ -a ] [ -A ] dsofile ... 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 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 mod- ule. 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 require- ments are fulfilled, you can easily extend your Apache server's functional- ity 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/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 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 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 Independend Code (PIC) to be able to use them for a DSO. For instance with GCC you always just have to use -fpic. For other C compilers please con- sult its manual page or watch for the flags apxs uses to compile the object files. For more details about DSO support in Apache, first read the background in- formation about DSO in htdocs/manual/dso.html, then read the documentation of mod_so. OPTIONS Common options: -n name 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 vari- able 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: -S variable=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 corre- sponding Makefile for even easier building 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 DSO 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 DSO file. If not specified and the name cannot be guessed from the files list, the fallback name mod_unknown.so is used. -D variable[=value] This option is directly passed through to the compilation com- mand(s). Use this to add your own defines to the build process. -I incdir This option is directly passed through to the compilation com- mand(s). Use this to add your own include directories to search to the build process. -L libdir This option is directly passed through to the linker command. Use this to add your own library directories to search to the build process. -l libname This option is directly passed through to the linker command. Use this to add your own libraries to search to the build process. -Wc,compiler-flags This option passes compiler-flags as additional flags to the compiler command. Use this to add local compiler-specific op- tions. -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 DSOs into the server's libexec directory. -a This activates the module by automatically adding a correspond- ing LoadModule line to Apache's httpd.conf configuration file, or by enabling it if it already exists. -A Same as option -a but the created LoadModule directive is pre- fixed with a hash sign (#), i.e. the module is just prepared for later activation but initially disabled. -e This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit 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 ex- tend Apache's server functionality. To accomplish 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 LoadMod- ule directive is present to load this DSO. To simplify this step apxs pro- vides an automatic way to install the DSO in the "libexec" 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/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 -A option, i.e. $ apxs -i -A mod_foo.c For a quick test of the apxs mechanism you can create a sample Apache mod- ule 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 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 apxs to compile complex modules outside the Apache source tree, like PHP3, because apxs 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. SEE ALSO apachectl(1), httpd(8).