apxs is a stand-alone utility for compiling modules dynamically without the need to use the configure script or have the Apache source code available. It does need Apache’s header files, though, which are copied to the location defined by --includedir when Apache is installed. However, it’s important to use an apxs that was built with the same configuration options as Apache; otherwise, it’ll make erroneous assumptions about where Apache’s various installation locations are.
At best, this will mean you can’t use apxs to install modules; at worst, apxs won’t be able to find the header files and simply won’t work at all.
However, apxs is totally useless for static Apache servers and isn’t even installed unless mod_so is built for dynamic module support. Administrators migrating to Apache 2 will be glad to learn that despite the substantial changes since version 1.3, the apxs command line hasn’t changed at all and is the same for Apache 2 as it was in Apache 1.3.
Platforms that offer prebuilt packages often put utilities such as apxs into a separate optional package along with the header files. If the standard Apache installation doesn’t include apxs, look for it in a package called apache-devel or similar.
apxs takes a list of C source files and libraries and compiles them into a dynamic module. To compile a simple module with only one source file, you could use something like this:
$ apxs -c mod_paranoia.c
This takes the source file and produces a dynamically loadable module called mod_paranoia.so. You can also compile stand-alone programs with apxs if you give it the -p option:
$ apxs -p -c program_that_uses_apache_libraries.c
apxs will happily accept more than one source file and will also recognize libraries and object files, adding them at the appropriate stage of the linking process:
$ apxs -c mod_paranoia.c libstayalert.a lasershandy.o
The -c option enables the use of a number of other code building options, most of which are passed on to the C compiler (see Table 3-13).
Table 3-13. apxs Command Line OptionsOption | Description |
-o outputfile | Sets the name of the resulting module file rather than inferring it from the name of the input files, for example, -o libparanoia.so. |
-D name=value | Sets a define value for the compiler to use when compiling the source code, for example, -D DEBUG_LEVEL=3. |
-I includedir | Adds a directory to the list of directories the compiler looks in for header files, for example, -I /include. |
-L libdir | Adds a directory to the list of directories the linker looks in for libraries at the linking stage, for example, -L /usr/local/libs. |
-l library | Adds a library to the list of libraries linked against the module, for example, -l ldap (assuming you have a libldap somewhere). |
-Wc,flag | Passes an arbitrary additional flag to the compiler. The comma is important to prevent the flag being interpreted by apxs, for example, -Wc,-O3 enables optimization on some compilers (for instance, gcc). -I is shorthand for -Wc,-I. |
-Wl,flag | Passes an arbitrary flag to the linker. The comma is important to prevent the flag being interpreted by apxs, for example, -Wl,-s strips symbols from the resulting object code on some compilers. -L is shorthand for -Wl,-L. |
$ apxs -i mod_paranoia.so
This builds the module and then installs it into the configured libexec directory.
In addition, you can use the -a option to have apxs modify Apache’s configuration (that is, httpd.conf) to add the LoadModule directive (plus an AddModule directive in Apache 1.3), so Apache will load the module when it’s restarted:
$ apxs -i -a mod_paranoia.so
If the directive already exists but is commented out, apxs is smart enough to just uncomment the existing line. This means that for Apache 1.3, the module loading order is preserved. (Apache 2 doesn’t rely on the order anyway, so it isn’t bothered by this issue).
When adding a new module to Apache 1.3, it’s important to realize that apxs has no special knowledge of where the module should be in the loading order, so it simply adds the LoadModule and AddModule directives to the end of their respective lists. Thus, before restarting Apache, you should take the time to check if this is the correct order. For example, it’s often necessary to move modules such as mod_setenvif to the end, so they can always act before third-party modules that might rely on the settings of environment variables.
If the module is already installed but the configuration doesn’t contain the corresponding directives to load it, you can instead use the -e option. This essentially tells apxs to recognize the -a flag but to not actually install the module:
$ apxs -e -a mod_paranoia.so
Alternatively, if you want to add the relevant lines but have them disabled currently, you can use the -A option instead, with either -i or -e. To install and configure the module in a disabled state, use this:
$ apxs -i -A mod_paranoia.so
To configure the module in a disabled state without installing it, use this:
$ apxs -e -A mod_paranoia.soBoth commands add the directives, but prefix them with a # to comment them out of the active configuration. If they’re already present, then they’re commented out in place; otherwise, they’re added to the end.
On rare occasions, the name of the module can’t be directly inferred from the name of the source file, in which case you have to specify it explicitly with the -n option to ensure that the directives added by -a or -A are correct:
$ apxs -i -n paranoid -a mod_paranoia.so
You can combine the build and install stages into one command by specifying both the -c and -i options at the same time:
$ apxs -c -i -a mod_paranoia.c
Generating Module Templates with apxs apxs can also generate template modules to kick start the development process for a new module with the -g option. For this to work with the -n option, you must specify the module name:
$ apxs -g -n paranoia
This will create a directory called paranoia within which apxs will generate a makefile that has various useful targets for building and testing the module and a source file called mod_paranoia.c. When compiled, the module provides no directives, but creates a handler you can use to prove that the module works. The handler name is based on the module name, in this case paranoia_handler.
Remarkably, you can combine all the previous stages to create, build, and install a module into Apache in just three commands:
$ apxs -g -n paranoia
$ cd paranoia
$ apxs -c -i -a mod_paranoia.c
Of course, this module will do very little, but you can test it by registering the default handler somewhere in the configuration:
AddHandler paranoia_handler .par
If you test this by creating a file called index.par (or any file with a.par extension), you’ll get a test page with the message:
The sample page from mod_paranoia.c
Overriding apxs Defaults and Using apxs in makefiles The Apache build process preconfigures apxs so that it automatically knows all the details of how Apache was built, where it was installed, and what compiler options were used. This allows apxs to build modules in the same way and to install them into the correct place automatically.
You may possibly need to add to or modify one of these presets, so apxs supplies the -S option to allow you to override any of its built-in presets. For example, to have apxs modify a configuration file that was moved to a different location after Apache was installed, you can override the SYSCONFDIR preset:
$ apxs -S SYSCONFDIR=/moved/conf/my_httpd.conf -i -a mod_paranoia.so
apxs is designed not just to build modules itself but also to provide a means for more complex modules to implement their own build processes. It enables them to use apxs to build and install themselves, automatically acquiring the correct defaults and path information, rather than having the information configured by hand. For this reason, apxs provides a query mode that allows configuration and compile-time details to be extracted with the -q option. Three groups of values can be returned by -q or set with -S
Table 3-14 shows the build settings.
Table 3-14. Compiler Options
Option | Description |
CC | Compiler command |
CFLAGS | Compiler flags |
CFLAGS_SHLIB | Additional compiler flags for building shared libraries (that’s, dynamic modules) |
LD_SHLIB | Linker command for linking shared libraries |
LDFLAGS_SHLIB | Additional linker flags for linking shared libraries |
LIBS_SHLIB | Additional libraries to link shared libraries against |
Table 3-15 shows the primary layout settings (these are also settable via configure options).
Table 3-15. Layout Specific Compiler Options
Option TARGET | Description Installation name (--with-program-name) |
PREFIX | Installation prefix (--prefix) |
SBINDIR | Location of system binaries (--sbindir) |
INCLUDEDIR | Location of header files (--includedir) |
LIBEXECDIR | Location of modules (--libexecdir) |
SYSCONFDIR | Location of configuration files (--sysconfdir) |
There are many values here, including locations such as bindir, sbindir, and datadir; their expanded versions in exp_bindir, exp_sbindir, and exp_datadir; and their locations relative to the prefix in rel_bindir, rel_sbindir, and rel_datadir. You can also query the operating system with OS, the list of configured dynamic modules with DSO_MODULES, and the subdirectories that will be examined for modules to build with MODULE_DIRS, amongst many others.
For example, to return the flags used by Apache to build dynamic modules, you’d use this:
$ apxs -q CFLAGS_SHLIB
Modules can use these values in their own makefiles, allowing them to compile independently of apxs without having to replicate the configuration setup work previously done by configure when Apache was built. For example, to use the same compiler and compiler options used to build Apache originally, you could put a line in the module’s makefile:
CC=`apxs -q CC`
CFLAGS=`apxs -q CFLAGS`
Summary In this chapter, you saw how to build the Web server you want by compiling the required source code components. You looked at the advantages and disadvantages of static and dynamic loading of Apache’s modules and saw how to customize Apache’s build process using the configure script for both Apache 1.3 and Apache 2. You also looked at the apxs script and saw how to build modules to add to an existing server.
There’s far more detail in this chapter than you really need to get a grip on right away; you can ignore many of the more advanced options until you encounter a situation that requires them. You can generate a simple configuration in only two commands—the rest is merely detail.
As you go on to configure Apache, you may need to come back and rebuild it—either to include some additional functionality into the server or to restructure its layout to suit some new requirement. As this chapter has shown, compiling source code is nothing to be afraid of—it gives you a great deal of control over Apache that you otherwise wouldn’t be able to get with a binary distribution, and for the most part it’s both easy and painless. Building applications from source tends to be an alien concept to the proprietary software world, but for open-source projects it’s both common and unremarkable.
No comments:
Post a Comment