-I dir vs. -isystem dir

Question

If I want to include directories to be searched for header files, which is the preferred way and why?

Answer 1

From the gcc documentation for -I:

Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. However, you should not use this option to add directories that contain vendor-supplied system header files (use -isystem for that). If you use more than one -I option, the directories are scanned in left-to-right order; the standard system directories come after.

If a standard system include directory, or a directory specified with -isystem, is also specified with -I, the -I option will be ignored. The directory will still be searched but as a system directory at its normal position in the system include chain. This is to ensure that GCC's procedure to fix buggy system headers and the ordering for the include_next directive are not inadvertently changed. If you really need to change the search order for system directories, use the -nostdinc and/or -isystem options.

So -I is probably the preferred option to specify the location of your header files, except for special cases such as vendor-supplied system headers.

Answer 2

You should use -I to specify the location of your headers.

The files you specify with -isystem are searched after -I is processed and receive a special treatment by gcc (the same as standard system headers).

Answer 3

One way to view this is to use headers that you control with -I and the ones you don't (system, 3rd party libs) with -isystem. The practical difference comes when warnings are enabled in that warnings which come from -isystem headers will be suppressed.