Resolving Include File Conflicts

In order to use the Apache API you need to pull in a number of API specific header files. Unfortunately these files contain declarations and macros that may conflict with declarations or macros in some of the standard C or C++ libraries.

The Apache API headers use an Apache header file called alloc.h while the system headers use a system header also called alloc.h. It is important that #include "alloc.h" be distinct from #include <alloc.h> in the eyes of the preprocessor.

All Apache API headers should be included as local files. All system files should be included as system files. The preprocessor should be directed to not search the default system wide directories for #include "foo.h" directives and to not search the directory containing Apache API headers for #include <foo.h> directives. See the Makefile example code and excert from the GNU cpp documentation below for details on how to do this with GNU cpp.

It is best practice to include the Apache API header files before including system wide headers. Any system headers that are needed by the Apache modules will themselves be included by the Apache headers. This be optional but it feels better to me.

Example

Source File

// Apache stuff
//  Its important to use "" instead of <> and to have the -I flags in
//  the right order in the Makefile because there is an Apache alloc.h
//  that is completely different from the system alloc.h.
#include "httpd.h"
#include "http_config.h"
#include "http_protocol.h"
#include "http_main.h"
#include "util_script.h"
#include "ap_config.h"
#include "http_log.h"

// System include files
#include <unistd.h>
#include <string>
#include <map>
#include <vector>
#include <iostream>
    

Makefile

# Change this line as appropriate
APACHE_INCLUDE_PATH=/usr/include/apache-1.3

# These are the switches you should use, you may not want to put them
# in CPPFLAGS, you may want to specify them elsewhere. Just make sure
# they end up getting to the preprocessor when the time comes. These
# flags must appear _before_ any other -I flags.
CPPFLAGS = -I$(APACHE_INCLUDE_PATH) -I. -I-

External Documentation

The following is from the GNU cpp manual page in the section titled Invoking the C Preprocessor:

`-I directory'
Add the directory directory to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. If you use more than one `-I' option, the directories are scanned in left-to-right order; the standard system directories come after.
`-I-'
Any directories specified with `-I' options before the `-I-' option are searched only for the case of `#include "file"'; they are not searched for `#include <file>'. If additional directories are specified with `-I' options after the `-I-', these directories are searched for all `#include' directives. In addition, the `-I-' option inhibits the use of the current directory as the first search directory for `#include "file"'. Therefore, the current directory is searched only if it is requested explicitly with `-I.'. Specifying both `-I-' and `-I.' allows you to control precisely which directories are searched before the current one and which are searched after.


Zachary C. Miller
Last modified: Tue Sep 14 01:21:26 CDT 1999