[APACHE DOCUMENTATION]

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: In addition, the following enhancements have been made:

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:

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:

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: (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