gcc/doc/cppenv.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 Environment variables affecting 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 @vtable @env
  13 @item CPATH
  14 @itemx C_INCLUDE_PATH
  15 @itemx CPLUS_INCLUDE_PATH
  16 @itemx OBJC_INCLUDE_PATH
  17 @c Commented out until ObjC++ is part of GCC:
  18 @c @itemx OBJCPLUS_INCLUDE_PATH
  19 Each variable's value is a list of directories separated by a special
  20 character, much like @env{PATH}, in which to look for header files.
  21 The special character, @code{PATH_SEPARATOR}, is target-dependent and
  22 determined at GCC build time.  For Microsoft Windows-based targets it is a
  23 semicolon, and for almost all other targets it is a colon.
  24
  25 @env{CPATH} specifies a list of directories to be searched as if
  26 specified with @option{-I}, but after any paths given with @option{-I}
  27 options on the command line.  This environment variable is used
  28 regardless of which language is being preprocessed.
  29
  30 The remaining environment variables apply only when preprocessing the
  31 particular language indicated.  Each specifies a list of directories
  32 to be searched as if specified with @option{-isystem}, but after any
  33 paths given with @option{-isystem} options on the command line.
  34
  35 In all these variables, an empty element instructs the compiler to
  36 search its current working directory.  Empty elements can appear at the
  37 beginning or end of a path.  For instance, if the value of
  38 @env{CPATH} is @code{:/special/include}, that has the same
  39 effect as @samp{@w{-I. -I/special/include}}.
  40
  41 @c man end
  42 @ifset cppmanual
  43 See also @ref{Search Path}.
  44 @end ifset
  45 @c man begin ENVIRONMENT
  46
  47 @item DEPENDENCIES_OUTPUT
  48 @cindex dependencies for make as output
  49 If this variable is set, its value specifies how to output
  50 dependencies for Make based on the non-system header files processed
  51 by the compiler.  System header files are ignored in the dependency
  52 output.
  53
  54 The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in
  55 which case the Make rules are written to that file, guessing the target
  56 name from the source file name.  Or the value can have the form
  57 @samp{@var{file} @var{target}}, in which case the rules are written to
  58 file @var{file} using @var{target} as the target name.
  59
  60 In other words, this environment variable is equivalent to combining
  61 the options @option{-MM} and @option{-MF}
  62 @ifset cppmanual
  63 (@pxref{Invocation}),
  64 @end ifset
  65 @ifclear cppmanual
  66 (@pxref{Preprocessor Options}),
  67 @end ifclear
  68 with an optional @option{-MT} switch too.
  69
  70 @item SUNPRO_DEPENDENCIES
  71 @cindex dependencies for make as output
  72 This variable is the same as @env{DEPENDENCIES_OUTPUT} (see above),
  73 except that system header files are not ignored, so it implies
  74 @option{-M} rather than @option{-MM}.  However, the dependence on the
  75 main input file is omitted.
  76 @ifset cppmanual
  77 @xref{Invocation}.
  78 @end ifset
  79 @ifclear cppmanual
  80 @xref{Preprocessor Options}.
  81 @end ifclear
  82
  83 @item SOURCE_DATE_EPOCH
  84 If this variable is set, its value specifies a UNIX timestamp to be
  85 used in replacement of the current date and time in the @code{__DATE__}
  86 and @code{__TIME__} macros, so that the embedded timestamps become
  87 reproducible.
  88
  89 The value of @env{SOURCE_DATE_EPOCH} must be a UNIX timestamp,
  90 defined as the number of seconds (excluding leap seconds) since
  91 01 Jan 1970 00:00:00 represented in ASCII; identical to the output of
  92 @samp{@command{date +%s}} on GNU/Linux and other systems that support the
  93 @code{%s} extension in the @code{date} command.
  94
  95 The value should be a known timestamp such as the last modification
  96 time of the source or package and it should be set by the build
  97 process.
  98
  99 @end vtable