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 Options
Once a module has been built, apxs can then install it into the place configured for modules (previously specified by the --libexecdir option), for example:
$ 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.so
Both 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.cGenerating 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
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.cOverriding 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
Table 3-15 shows the primary layout settings (these are also settable via configure options).
Table 3-15. Layout Specific Compiler Options
In a configured Apache 2 source distribution, the configuration settings are stored in config_vars.mk.
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`
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.
blog comments powered by Disqus