Apache HTTP Server Version 1.3

Source Re-organisation

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.

Summary of Changes

The source changes are:

The non-module source files have moved from
src into src/main

The module source files previously in src
have moved to src/modules/standard

The support directory is now in
src/support

The existing symbol names used for global Apache function
and variable identifiers have been renamed in the source.
This way namespace conflicts are avoided when linking Apache
with third-party libraries. See the file
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:

OS abstractions can be added in the 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.

Module authors can give simpler instructions for adding
their modules to Apache compilation. They can also now
provide compile time information required by
Configure, such as additional libraries
required.

Module authors can distribute pre-compiled (.a or .o)
versions of their modules if required, along with a "module
definition file" which contains the information required by
Configure.

All the sub-directories (main, modules/* and os/*) are
built as libraries.

The new Apache Autoconf-style Interface (APACI) script
named configure replaced the old top-level
Makefile and
src/helpers/InstallApache stuff.

Adding Modules

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:

Put mod_foo.c into the directory
src/modules/extra

Go to the src directory and add the
following line to ConfigurationAddModule modules/extra/mod_foo.o

Run ./Configure

Run make

New Facilities for Module Authors

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:

Simplified Configuration command AddModule
which only requires a path to the module source or object
file

If the module requires compile time options (such as
extra libraries) these can be specified in the module file
source or an external "module definition file".

If a module is distributed as binary (.o or .a) then an
external "module definition file" can also be distributed
which gives the information Configure needs to add the
module, such as extra libraries and the module's structure
name.

Modules can be installed anywhere on the file system,
although a directory under src/modules is
recommended.

If the module is in its own directory, Apache can
automatically create a Makefile to build the module given a
file containing the module's dependencies.

For building a third-party module
outside the Apache source tree the new
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.

Building a simple source distribution

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:

mod_demo/mod_demo.c

mod_demo/Makefile.tmpl

(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).

Adding Compile time Information

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:

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.

Module Definition Information for Binary Distribitions

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-STARTetc. For example: