gcc/doc/cppdiropts.texi

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