gcc/doc/cppdiropts.texi

   1 @c Copyright (C) 1999-2020 Free Software Foundation, Inc.
   2 @c This is part of the CPP and GCC manuals.
   3 @c For copying conditions, see the file gcc.texi.
   4
   5 @c ---------------------------------------------------------------------
   6 @c Options affecting include directory search in the preprocessor
   7 @c ---------------------------------------------------------------------
   8
   9 @c If this file is included with the flag ``cppmanual'' set, it is
  10 @c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
  11
  12 @item -I @var{dir}
  13 @itemx -iquote @var{dir}
  14 @itemx -isystem @var{dir}
  15 @itemx -idirafter @var{dir}
  16 @opindex I
  17 @opindex iquote
  18 @opindex isystem
  19 @opindex idirafter
  20 Add the directory @var{dir} to the list of directories to be searched
  21 for header files during preprocessing.
  22 @ifset cppmanual
  23 @xref{Search Path}.
  24 @end ifset
  25 If @var{dir} begins with @samp{=} or @code{$SYSROOT}, then the @samp{=}
  26 or @code{$SYSROOT} is replaced by the sysroot prefix; see
  27 @option{--sysroot} and @option{-isysroot}.
  28
  29 Directories specified with @option{-iquote} apply only to the quote
  30 form of the directive, @code{@w{#include "@var{file}"}}.
  31 Directories specified with @option{-I}, @option{-isystem},
  32 or @option{-idirafter} apply to lookup for both the
  33 @code{@w{#include "@var{file}"}} and
  34 @code{@w{#include <@var{file}>}} directives.
  35
  36 You can specify any number or combination of these options on the
  37 command line to search for header files in several directories.
  38 The lookup order is as follows:
  39
  40 @enumerate
  41 @item
  42 For the quote form of the include directive, the directory of the current
  43 file is searched first.
  44
  45 @item
  46 For the quote form of the include directive, the directories specified
  47 by @option{-iquote} options are searched in left-to-right order,
  48 as they appear on the command line.
  49
  50 @item
  51 Directories specified with @option{-I} options are scanned in
  52 left-to-right order.
  53
  54 @item
  55 Directories specified with @option{-isystem} options are scanned in
  56 left-to-right order.
  57
  58 @item
  59 Standard system directories are scanned.
  60
  61 @item
  62 Directories specified with @option{-idirafter} options are scanned in
  63 left-to-right order.
  64 @end enumerate
  65
  66 You can use @option{-I} to override a system header
  67 file, substituting your own version, since these directories are
  68 searched before the standard system header file directories.
  69 However, you should
  70 not use this option to add directories that contain vendor-supplied
  71 system header files; use @option{-isystem} for that.
  72
  73 The @option{-isystem} and @option{-idirafter} options also mark the directory
  74 as a system directory, so that it gets the same special treatment that
  75 is applied to the standard system directories.
  76 @ifset cppmanual
  77 @xref{System Headers}.
  78 @end ifset
  79
  80 If a standard system include directory, or a directory specified with
  81 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
  82 option is ignored.  The directory is still searched but as a
  83 system directory at its normal position in the system include chain.
  84 This is to ensure that GCC's procedure to fix buggy system headers and
  85 the ordering for the @code{#include_next} directive are not inadvertently
  86 changed.
  87 If you really need to change the search order for system directories,
  88 use the @option{-nostdinc} and/or @option{-isystem} options.
  89 @ifset cppmanual
  90 @xref{System Headers}.
  91 @end ifset
  92
  93 @item -I-
  94 @opindex I-
  95 Split the include path.
  96 This option has been deprecated.  Please use @option{-iquote} instead for
  97 @option{-I} directories before the @option{-I-} and remove the @option{-I-}
  98 option.
  99
 100 Any directories specified with @option{-I}
 101 options before @option{-I-} are searched only for headers requested with
 102 @code{@w{#include "@var{file}"}}; they are not searched for
 103 @code{@w{#include <@var{file}>}}.  If additional directories are
 104 specified with @option{-I} options after the @option{-I-}, those
 105 directories are searched for all @samp{#include} directives.
 106
 107 In addition, @option{-I-} inhibits the use of the directory of the current
 108 file directory as the first search directory for @code{@w{#include
 109 "@var{file}"}}.  There is no way to override this effect of @option{-I-}.
 110 @ifset cppmanual
 111 @xref{Search Path}.
 112 @end ifset
 113
 114 @item -iprefix @var{prefix}
 115 @opindex iprefix
 116 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
 117 options.  If the prefix represents a directory, you should include the
 118 final @samp{/}.
 119
 120 @item -iwithprefix @var{dir}
 121 @itemx -iwithprefixbefore @var{dir}
 122 @opindex iwithprefix
 123 @opindex iwithprefixbefore
 124 Append @var{dir} to the prefix specified previously with
 125 @option{-iprefix}, and add the resulting directory to the include search
 126 path.  @option{-iwithprefixbefore} puts it in the same place @option{-I}
 127 would; @option{-iwithprefix} puts it where @option{-idirafter} would.
 128
 129 @item -isysroot @var{dir}
 130 @opindex isysroot
 131 This option is like the @option{--sysroot} option, but applies only to
 132 header files (except for Darwin targets, where it applies to both header
 133 files and libraries).  See the @option{--sysroot} option for more
 134 information.
 135
 136 @item -imultilib @var{dir}
 137 @opindex imultilib
 138 Use @var{dir} as a subdirectory of the directory containing
 139 target-specific C++ headers.
 140
 141 @item -nostdinc
 142 @opindex nostdinc
 143 Do not search the standard system directories for header files.
 144 Only the directories explicitly specified with @option{-I},
 145 @option{-iquote}, @option{-isystem}, and/or @option{-idirafter}
 146 options (and the directory of the current file, if appropriate)
 147 are searched.
 148
 149 @item -nostdinc++
 150 @opindex nostdinc++
 151 Do not search for header files in the C++-specific standard directories,
 152 but do still search the other standard directories.  (This option is
 153 used when building the C++ library.)
 154