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