As of 1.3, the Apache source directories have been re-organised. This re-organisation is designed to simplify the directory structure, make it easier to add additional modules, and to give module authors a way of specifying compile time options or distribute binary modules.
The source changes are:
src
into src/main
src
have moved to src/modules/standard
support
directory is now in src/support
src/include/compat.h
both for the list of renamed symbol names and for a way to get source backward compatibility in existing third-party module sources.In addition, the following enhancements have been made:
src/os
directory. Currently this contains information for unix, OS/2 and Windows 32 platforms.Configuration
syntax has been simplified for adding new modules. Users no longer need to enter the module's structure name. In addition, new modules can be located anywhere on the file system, or typically in new or existing directories under src/modules
.Configure
, such as additional libraries required.Configure
.configure
replaced the old top-level Makefile
and src/helpers/InstallApache
stuff.Modules are added to Apache by adding a reference to them in src/Configuration
then running Configure
and make
. In earlier version of Apache before 1.3, the line added to Configuration looked like this:
Module status_module mod_status.o
From 1.3 onwards, the AddModule
line should be used instead, and typically looks like this:
AddModule modules/standard/mod_status.o
The argument to AddModule is the path, relative to src
, to the module file's source or object file.
Normally when adding a module you should follow the instructions of the module author. However if the module comes as a single source file, say mod_foo.c, then the recommended way to add the module to Apache is as follows:
mod_foo.c
into the directory src/modules/extra
src
directory and add the following line to Configuration
AddModule modules/extra/mod_foo.o
./Configure
make
In previous releases of Apache, new modules were added to the src
directory, and if the module required any additional compilation options (such as libraries) they would have to be added to Configuration
. Also the user would have to be told the module's structure name to add on the Module line of Configuration
.
From Apache 1.3 onwards, module authors can make use of these new features:
Configuration
command AddModule which only requires a path to the module source or object filesrc/modules
is recommended.apxs
support tool can be used to compile the module into a dynamic shared object (DSO), install it into the existing Apache installation and optionally activating it in the Apache httpd.conf
file. The only requirement is that Apache has DSO-support for the used platform and the module mod_so
was built into the server binary httpd
.The rest of this document shows how to package modules for Apache 1.3 and later and what to tell end-users of the module.
Consider a simple add-on module, distributed as a single file. For example, say it is called mod_demo.c. The archive for this module should consist of two files, in a suitable directory name. For example:
(Of course end-user instructions, README's, etc can also be supplied in the archive). The end user should be told to extract this archive in the src/modules
directory of their Apache source tree. This will create a new directory src/modules/mod_demo
. Then they need to add the following line to the Configuration
file:
AddModule modules/mod_demo/mod_demo.o
then run Configure
and make
as normal.
The mod_demo/Makefile.tmpl
should contain the dependencies of the module source. For example, a simple module which just interfaces to some standard Apache module API functions might look this this:
mod_demo.o: mod_demo.c $(INCDIR)/httpd.h $(INCDIR)/http_protocol.h
When the user runs Configure
Apache will create a full makefile to build this module. If this module also requires some additional built-time options to be given, such as libraries, see the next section.
If the module also comes with header files, these can be added to the archive. If the module consists of multiple source files it can be built into a library file using a supplied makefile. In this case, distribute the makefile as mod_demo/Makefile
and do not include a mod_demo/Makefile.tmpl
. If Configure
sees a Makefile.tmpl
it assumes it is safe to overwrite any existing Makefile
.
See the Apache src/modules/standard
for an example of a module directory where the makefile is created automatically from a Makefile.tmpl file (note that this directory also shows how to distribute multiple modules in a single directory). See src/modules/proxy
and src/modules/example
for examples of modules built using custom makefiles (to build a library and an object file, respectively).
Apache source files (or module definition files, see below) can contain information used by Configure
to add compile-time options such as additional libraries. For example, if mod_demo in the example above also requires that Apache be linked against a DBM library, then the following text could be inserted into the mod_demo.c source:
/* * Module definition information - the part between the -START and -END * lines below is used by Configure. This could be stored in a separate * instead. * * MODULE-DEFINITION-START * Name: demo_module * ConfigStart LIBS="$LIBS $DBM_LIB" if [ "X$DBM_LIB" != "X" ]; then echo " + using $DBM_LIB for mod_demo" fi * ConfigEnd * MODULE-DEFINITION-END */
Note that this is contained inside a C language comment to hide it from the compiler. Anything between the lines which contains MODULE-DEFINITION-START
and MODULE-DEFINITION-END
is used by Configure
. The Name:
line gives the module's structure name. This is not really necessary in this case since if not present Configure
will guess at a name based on the filename (e.g., given "mod_demo" it will remove the leading "mod_" and append "_module" to get a structure name. This works with all modules distributed with Apache).
The lines between ConfigStart
and ConfigEnd
as executed by Configure
and can be used to add compile-time options and libraries. In this case it adds the DBM library (from $DBM_LIB) to the standard compilation libraries ($LIB) and displays a message.
See the default distribution's mod_auth_dbm.c for an example of an embedded module definition.
If the module is to be distributed as binary (object or library) rather than source, it is not possible to add the module definition information to the source file. In this case it can be placed in a separate file which has the same base name as the object or library file, but with a .module
extension. So, for example, if the distributed module object file is mod_demo.o, the module definition file should be called mod_demo.module. It contains the same information as above, but does not need to be inside a C comment or delimited with MODULE-DEFINITION-START
etc. For example:
Name: demo_module ConfigStart LIBS="$LIBS $DBM_LIB" if [ "X$DBM_LIB" != "X" ]; then echo " + using $DBM_LIB for mod_demo" fi ConfigEnd
See the default distribution's mod_auth_db.module for an example of a separate module definition file.