skip to content

With GCC, in what order are -iquote, -I and -isystem directories searched, and how do -D and -U define macros?

level: middleimportance: should knowfreq 55%

answer

  1. quote form starts closer to home
  2. current dir, -iquote, -I, -isystem
  3. -isystem silences warnings
  4. -D name means 1
  5. -D and -U run in order

basics

~20 s

For #include "..." GCC searches the including file's directory, then -iquote, then -I, then -isystem and the system directories; #include <...> starts at -I. -D name defines it as 1, -D name=value sets a value, and -U cancels a definition.

solid answer

~40 s

GCC keeps two search chains. `#include "file"` looks first in the **directory of the file doing the include**, then in `-iquote` directories, then falls through to the angle-bracket chain. `#include <file>` starts at the `-I` directories (left to right), then `-isystem` directories, then the standard system directories, and finally `-idirafter`. Headers found through `-isystem` are treated as **system headers**, so GCC suppresses their warnings, which is why third-party includes usually go there. `-D NAME` defines `NAME` as `1`; `-D NAME=VALUE` defines it as if `#define NAME VALUE` appeared; `-U NAME` cancels a built-in or earlier definition. `-D` and `-U` are processed in command-line order, and `-include` files after all of them. `g++ -v` prints the effective search list and `-H` prints each header as it is opened.

code

bash · 3 lines
bash
g++ -iquote src -I include -isystem third_party/include \
    -DNDEBUG -DLOG_LEVEL=2 -UFEATURE_X \
    -v -E main.cpp -o /dev/null 2>&1 | sed -n '/search starts here/,/End of search/p'

go deeper

for a junior

Know that -I adds include directories, -D defines a macro and -U removes one, and that quotes and angle brackets search differently.

for a middle

Give the exact search order for both include forms, explain why third-party headers go on -isystem, and show the value -D gives by default.

for a senior

Diagnose a wrong header with -H and -v, and catch command-line macros that differ between translation units of one program.

for a principal

Set the rule for which directories are system headers in the build, accepting that warnings from those headers will never be seen.

## Two search chains The preprocessor resolves `#include` against an ordered list of directories, and the two spellings use different starting points: 1. **`#include "file"`** searches the directory containing the current file, then the **quote directories** added with `-iquote`, then everything the angle form searches. 2. **`#include <file>`** searches the `-I` directories, then `-isystem` directories, then the compiler's standard system directories, then `-idirafter` directories. | Option | Searched for `"..."` | Searched for `<...>` | Treated as system headers | |---|---|---|---| | directory of the including file | yes, first | no | no | | `-iquote dir` | yes | no | no | | `-I dir` | yes | yes, first | no | | `-isystem dir` | yes | yes, after `-I` | **yes** | | standard system directories | yes | yes | yes | | `-idirafter dir` | yes | yes, last | **yes** | Several `-I` options are searched **left to right**, so the first matching directory wins. That is a feature when you deliberately shadow a header and a source of baffling bugs when two libraries ship a `config.h`. ## Why -isystem exists GCC gives system headers special treatment: all warnings except `#warning` are suppressed while it processes them, because operating-system and library headers often cannot be written in strictly conforming code. Directories added with `-isystem` and `-idirafter` get the same treatment. Teams therefore: - put **their own** headers on `-I` or `-iquote`, so `-Wall -Wextra -Werror` applies to them; - put **third-party** headers on `-isystem`, so a library's warnings do not break the build. The cost is real: a genuine problem in a template from that library is silenced too. `#pragma GCC system_header` has the same effect from inside a header, for the rest of that file. ## Seeing the search in action - `g++ -v -E file.cpp -o /dev/null` prints `#include "..." search starts here:` and `#include <...> search starts here:` followed by the directories in order. - `g++ -H -c file.cpp` prints every header as it is opened, indented by include depth, which answers "which `config.h` did we actually get?" ## Defining macros on the command line `-D` and `-U` act as if directives were written before the first line of the file: - `-D NAME` defines `NAME` with the value `1`. `-DNDEBUG` is therefore `#define NDEBUG 1`, which `<cassert>` only tests for existence. - `-D NAME=VALUE` tokenizes `VALUE` as if it appeared in a `#define`, so `-DVERSION=3` gives `VERSION` the token `3`. String values need shell quoting: `-DBUILD_ID='"abc123"'`. - A function-like macro needs its parameter list before `=`, and quoting: `-D'MAX(a,b)=((a)>(b)?(a):(b))'`. - `-U NAME` cancels any previous definition, whether built in or from an earlier `-D`. The manual adds two ordering rules: 1. `-D` and `-U` are processed **in the order given**, so `-DFOO -UFOO` leaves `FOO` undefined, and `-UFOO -DFOO` leaves it defined. 2. All `-include file` and `-imacros file` options are processed **after** every `-D` and `-U`. ## Command-line macros versus a configuration header Two common ways to feed build settings into code: - **`-D` flags** keep the setting in the build files. They are visible in every compile command, which helps reproducing a build, but every file sees the same value only if the build system passes the same flags to every file. - **A generated header** such as `config.h`, included where needed, keeps the settings in one file that can be inspected and diffed. `-include file` sits between the two: it processes `file` as if `#include "file"` were the first line of the main source, searching the preprocessor's working directory first and then the rest of the quote chain. It is a way to inject a configuration or precompiled header into every translation unit without editing them. ## Common traps - A macro defined on the command line differs between two translation units of one program, so an inline function or class layout differs between them. That is an ODR problem the linker will not report, covered with the compilation model. - A local header named like a standard one shadows it when its directory comes first. - `-I.` adds the compiler's working directory, which in an out-of-tree build is the build directory, not the source directory.

  • When would you choose -iquote over -I?
    When a directory holds project headers that must never shadow a system or library header reached with angle brackets. `-iquote` only affects `#include "..."`, so a local file named like a standard header cannot capture an `#include <...>`.
  • Why can -isystem hide a real bug?
    Warnings are suppressed while GCC processes headers from `-isystem` directories, including warnings raised inside templates defined there. A conversion or null dereference warning in a library template instantiated with your types may never be shown.

  • -I directories are only searched for #include "..." and never for angle brackets.
  • -DNDEBUG defines NDEBUG with an empty value.
  • -isystem directories are searched before -I directories.
  • The order of -D and -U options on the command line does not matter.
  • Headers found through -isystem are compiled with warnings promoted to errors.