16.3. Finding `#include` files in repositories
Prev | Chapter 16. Building From Code Repositories | Next

## 16.3. Finding `#include` files in repositories

You've already seen that SCons will scan the contents of a source file for `#include` file names and realize that targets built from that source file also depend on the `#include` file(s). For each directory in the `$CPPPATH` list, SCons will actually search the corresponding directories in any repository trees and establish the correct dependencies on any `#include` files that it finds in repository directory.

Unless the C compiler also knows about these directories in the repository trees, though, it will be unable to find the `#include` files. If, for example, the `hello.c` file in our previous example includes the `hello.h` in its current directory, and the `hello.h` only exists in the repository:

    % scons -Q
    cc -o hello.o -c hello.c
    hello.c:1: hello.h: No such file or directory

In order to inform the C compiler about the repositories, SCons will add appropriate source file inclusion directives (`-I` or `/I` flags) to the compilation commands for each directory in the `$CPPPATH` list. So if you add the current directory to the construction environment `$CPPPATH`:

    env = Environment(CPPPATH=['.'])
    env.Program('hello.c')
    Repository('/usr/repository1')

Then re-executing SCons yields:

    % scons -Q
    cc -o hello.o -c -I. -I/usr/repository1 hello.c
    cc -o hello hello.o

The order of the `-I` options replicates, for the C preprocessor, the same repository-directory search path that SCons uses for its own dependency analysis. If there are multiple repositories and multiple `$CPPPATH` directories, SCons will add the repository directories to the beginning of each `$CPPPATH` directory, rapidly multiplying the number of `-I` flags. If, for example, the `$CPPPATH` contains three directories (and shorter repository path names!):

    env = Environment(CPPPATH=['dir1', 'dir2', 'dir3'])
    env.Program('hello.c')
    Repository('/r1', '/r2')

Then you'll end up with nine `-I` options on the command line, three (for each of the `$CPPPATH` directories) times three (for the local directory plus the two repositories):

    % scons -Q
    cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c
    cc -o hello hello.o

### 16.3.1. Limitations on `#include` files in repositories

SCons relies on the C compiler's `-I` options to control the order in which the preprocessor will search the repository directories for `#include` files. This causes a problem, however, with how the C preprocessor handles `#include` lines with the file name included in double-quotes.

As you've seen, SCons will compile the `hello.c` file from the repository if it doesn't exist in the local directory. If, however, the `hello.c` file in the repository contains a `#include` line with the file name in double quotes:

    #include "hello.h"
    int
    main(int argc, char *argv[])
    {
        printf(HELLO_MESSAGE);
        return (0);
    }

Then the C preprocessor will always use a `hello.h` file from the repository directory first, even if there is a `hello.h` file in the local directory, despite the fact that the command line specifies `-I` as the first option:

    % scons -Q
    cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c
    cc -o hello hello.o

This behavior of the C preprocessor--always search for a `#include` file in double-quotes first in the same directory as the source file, and only then search the `-I`--can not, in general, be changed. In other words, it's a limitation that must be lived with if you want to use code repositories in this way. There are three ways you can possibly work around this C preprocessor behavior:

1. Some modern versions of C compilers do have an option to disable or control this behavior. If so, add that option to `$CFLAGS` (or `$CXXFLAGS`, or both) in your construction environments. Make sure the option is used for all construction environment that use C preprocessing!

2. Change all occurrences of `#include "file.h"` to `#include <file.h>`. Use of `#include` with angle brackets does not have the same behavior--the `-I` directories are searched first for `#include` files--which gives SCons direct control over the list of directories the C preprocessor will search.

3. Require that everyone working with compilation from repositories check out and work on entire directories of files, not individual files. (If you use local wrapper scripts around your source code control system's command, you could add logic to enforce this restriction there.

Prev | Up | Next
16.2. Finding source files in repositories | Home | 16.4. Finding the `SConstruct` file in repositories