3.7. Defining the Include File Directory Search Path¶
In C/C++, an #include preprocessor directive tells the compiler to read C/C++ source statements from another file. When specifying the file, you can enclose the filename in double quotes or in angle brackets. The filename can be a complete pathname, a relative pathname, or a filename with no path information.
When searching for the specified include file, the compiler will incorporate the notion of an include file directory search path into the search.
3.7.1. cl2000 Include File Directory Search Path¶
The cl2000 compiler supports the notion of an include file search path directory. It can make use of environment variables to help extend the include file directory search path.
Using the cl2000 compiler, the include file directory search path is defined in one of two ways:
If you enclose the file specification in double quotes (” “), the compiler searches for the file in the following directories in this order:
The directory of the file that contains the #include preprocessor directive
Directories named in one or more --include_path options in the order in which the options are specified in the compiler invocation
Directories listed in the C2000_C_DIR environment variable definition
If you enclose the file specification in angle brackets (< >), the compiler searches for the file in the following directories in this order:
Directories named in one or more --include_file options in the order in which the options are specified in the compiler invocation
Directories listed in the C2000_C_DIR environment variable definition
By default, the cl2000 compiler begins with an empty include file directory search path. The recommended environment variable that serves as a sort of baseline definition of the include file directory search path is C2000_C_DIR, but the cl2000 compiler also honors the cl2000 environment variable C_DIR. In addition, the cl2000 compiler allows the C2000_C_OPTION environment variable to define a set of compiler options to be used as if they were on the command line.
3.7.2. c29clang Include File Directory Search Path¶
The c29clang compiler also has a notion of an include file search path directory and it can also make use of environment variables to help extend the include file directory search path. However, the c29clang’s definition of the include file directory search path incorporates a builtin clang include file directory and standard system directories that contain C and C++ runtime header files.
When using the c29clang compiler to process an #include preprocessor directive, the include file directory search path is defined in one of two ways:
If you enclose the file specification in double quotes (” “), the compiler searches for the file in the following directories in this order:
The directory of the file that contains the #include preprocessor directive
Directories named in one or more -I options in the order in which the options are specified in the compiler invocation
Directories listed in an applicable environment variable definition
C++ runtime header file directory (if compiling a C++ source file)
Compiler builtin include directory
Standard system include directories
If you enclose the file specification in angle brackets (< >), the compiler searches for the file in the following directories in this order:
Directories named in one or more -I options in the order in which the options are specified in the compiler invocation
Directories listed in an applicable environment variable definition
C++ runtime header file directory (if compiling a C++ source file)
Compiler builtin include directory
Standard system include directories
By default, the c29clang compiler populates the include file directory search path with the builtin include directory and the standard system include directories that are set up when the c29clang compiler tools are installed. For example, the following include file directories are installed with the c29clang 1.0.0-alpha.1 compiler tools:
C++ runtime header file directory: <install area>/lib/generic/include/c++/v1
Compiler builtin include directory: <install area>/lib/clang/10.0.0/include
Standard system include directory: <install area>/lib/generic/include/c
The following command-line options are available in the c29clang compiler to manage whether or not these installed include directories are incorporated into a given compilation:
-nostdinc - do not incorporate the C++ runtime header file directory, the compiler builtin include directory, or the standard system include directory in the default definition of the include file directory search path
-nostdlibinc - do not incorporate the C++ runtime header file directory or the standard system include directory into the include file directory search path, but do incorporate the compiler’s builtin include directory
-nobuiltininc - do not incorporate the compiler’s builtin include directory into the include file directory search path, but do incorporate the C++ runtime header file directory and the standard system include directory
You may also control the include file directory search path through definitions of the CPATH, C_INCLUDE_PATH (C source files only), or CPLUS_INCLUDE_PATH (C++ source files only) environment variables.
The C2000_C_DIR, C_DIR, and C2000_C_OPTION environment variables are not supported by the c29clang compiler, and should be migrated as appropriate.
3.7.3. Adding to the Include File Directory Search Paths with Command-Line Options¶
As indicated above, the include file directory search path can be controlled using the compiler command-line.
cl2000 Option (and alias) |
c29clang Option |
|---|---|
--include_path=<dir> (-I=<dir>) (-i=<dir>) |
-I |
When using the cl2000 compiler, the --include_path option allows a user to specify a semi-colon separated list of one or more directory paths in which the compiler will search for an include file in accordance with the rules indicated in the above “cl2000 Include File Directory Search Path” section.
Likewise, using the c29clang compiler, the -I option allows a user to specify a semi-colon separated list of one or more directory paths in which the compiler will search for an include file in accordance with the rules indicated in the above “c29clang Include File Directory Search Path” section.
Also see migration of the --preinclude option in Specifying Source Files and File Extensions.