2.8. 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.
2.8.1. armcl Include File Directory Search Path¶
The armcl 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 armcl 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 TI_ARM_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 TI_ARM_C_DIR environment variable definition
By default, the armcl 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 TI_ARM_C_DIR, but the armcl compiler will also honor legacy environment variables TMS470_C_DIR and C_DIR.
2.8.2. tiarmclang Include File Directory Search Path¶
The tiarmclang 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 tiarmclang’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 tiarmclang 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 tiarmclang 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 tiarmclang compiler tools are installed. For example, the following include file directories are installed with the tiarmclang 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 tiarmclang 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 annotate the include file directory search path by defining the C_INCLUDE_PATH environment variable when compiling a C source file, or the CPLUS_INCLUDE_PATH environment variable when compiling a C++ source file.
2.8.3. Adding to the Include File Directory Search Paths with Command-Line Options¶
As indicated above, the definition of the include file directory search path can be annotated on the compiler command-line.
armcl Option (and alias) |
tiarmclang Option |
|---|---|
--include_path=<dir> (-I=<dir>) (-i=<dir>) |
-I |
When using the armcl 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 “armcl Include File Directory Search Path” section.
Likewise, using the tiarmclang 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 “tiarmclang Include File Directory Search Path” section.