Prefixinclude Caveats

Alcatel-Lucent nmake release lu3.5 introduced an enhanced prefixinclude feature to allow better integration with tools which have native support for -I- but not prefixinclude. Though this does allow easier integration with some compilers there are some important caveats which the user should understand.

What is the Prefixinclude Feature?

Standard preprocessors search for files included using #include "..." first in the directory of the parent file. This behavior violates the viewpath so nmake supplies a preprocessor that supports -I- to enable an alternate search strategy. However, it is not uncommon for a file included with a directory prefix (ie. "dir/file1.h") to include a second file in the same physical directory without specifying the prefix (ie. "file2.h".) To retain compatibility with this coding practice nmake and the supplied preprocessor use the prefixinclude feature to search for file2.h by first applying the prefix and searching for "dir/file2.h" and if that isn't found then searching for "file2.h".

The base rules define prefixinclude=1 by default, so the feature is enabled. It can be disabled by setting prefixinclude=0.

Enhancement for Native Preprocessors

There are now several compilers with native -I- support. However, only the nmake supplied preprocessor and HP aC++ is known to support prefixinclude. Compile errors may result from using -I- without prefixinclude when the compiler is unabel to locate include files using the above mentioned coding practice.

Release lu3.5 enhances nmake's prefixinclude support. When using a native preprocessor with -I- support that does not support prefixinclude, nmake will add the necessary prefix directories to the -I search list on the compile command line. This allows the native preprocessor to locate the headers without having native prefixinclude support.

The nmake Preprocessor

Even though the native preprocessor is used by default when it supports -I-, the use of the nmake supplied preprocessor is still an option. The nmake supplied preprocessor will provide more transparent header search processing, but requires the use of an external preprocessor. Some compilers integrate well with an external preprocessor while others depend on their native preprocessor for particular features or unique behavior. To use the nmake supplied preprocessor set nativepp=0.

Caveats

While nmake's enhanced prefixinclude feature solves some problems with native preprocessors, it is not a full replacement for native prefixinclude support. There are situations where code changes may be necessary to insure the native preprocessor picks up the correct headers. The following examples illustrate these situations and provide coding solutions. The alternative is to use the nmake supplied preprocessor as described above.

Example 1

There are two include directories, include/sub1/ and include/sub2/. A top-level source file, main.c, includes files in both of these subdirectories, say "sub1/f1.h" and "sub2/f2.h". Suppose sub1/f1.h includes a file "x.h"", and sub2/f2.h also includes a file "x.h". By normal C include semantics, we want sub1/f1.h to pick up sub1/x.h, and sub2/f2.h to pick up sub2/x.h. There is no sequence of -I options that will cause sub1/f1.h to always pick up sub1/x.h and sub2/f2.h to always pick up sub2/x.h. If we say "-Iinclude/sub1 -Iinclude/sub2", then both sub1/f1.h and sub2/f2.h will get sub1/x.h, not what we want.

If the preprocessor does not support prefixinclude then to use this approach the above case will require code changes. For both headers, x.h must be included with its directory prefix to distinguish between them. The changes would look like:

    include/sub1/f1.h:
	#include "sub1/x.h"

    include/sub2/f2.h:
	#include "sub2/x.h"

Example 2

There is an include directory called include/sub1/. A top-level source file, main.c, includes "f1.h" and "sub1/f2.h". File sub1/f2.h includes "x.h".

Suppose the following files exist:

• include/f1.h
• include/sub1/f1.h
• include/sub1/f2.h
• include/x.h
• include/sub1/x.h

Using normal C include semantics, we want to pick up:

• include/f1.h
• include/sub1/f2.h
• include/sub1/x.h

Using "-Iinclude -Iinclude/sub1" will not pick up the desired files, the following will be included:

• include/f1.h
• include/sub1/f2.h
• include/x.h

Switching the arguments to "-Iinclude/sub1 -Iinclude" will still not pick up the correct set of files. The following will be included:

• include/sub1/f1.h
• include/sub1/f2.h
• include/sub1/x.h

If the preprocessor does not support prefixinclude then this case will require code changes. The header x.h must be included with its directory prefix. The change would look like:

    include/sub1/f2.h:
	#include "sub1/x.h"