+2017-01-07 Sandra Loosemore <sandra@codesourcery.com>
+
+ * doc/cppdiropts.texi: Merge documentation of -I, -iquote,
+ -isystem, and -idirafter. Copy-edit.
+ * doc/cppopts.texi: Copy-edit. Remove contradiction about
+ default for -ftrack-macro-expansion. Delete obsolete and
+ badly-formatted implementation details about -fdebug-cpp output.
+ * doc/cppwarnopts.texi: Copy-edit.
+
2017-01-07 David Malcolm <dmalcolm@redhat.com>
PR c++/72803
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
@item -I @var{dir}
+@itemx -iquote @var{dir}
+@itemx -isystem @var{dir}
+@itemx -idirafter @var{dir}
@opindex I
+@opindex iquote
+@opindex isystem
+@opindex idirafter
Add the directory @var{dir} to the list of directories to be searched
-for header files.
+for header files during preprocessing.
@ifset cppmanual
@xref{Search Path}.
@end ifset
-If you use more than
-one @option{-I} option, the directories are scanned in left-to-right
-order; the standard system directories come after.
+If @var{dir} begins with @samp{=}, then the @samp{=} is replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+Directories specified with @option{-iquote} apply only to the quote
+form of the directive, @code{@w{#include "@var{file}"}}.
+Directories specified with @option{-I}, @option{-isystem},
+or @option{-idirafter} apply to lookup for both the
+@code{@w{#include "@var{file}"}} and
+@code{@w{#include <@var{file}>}} directives.
+
+You can specify any number or combination of these options on the
+command line to search for header files in several directories.
+The lookup order is as follows:
+
+@enumerate
+@item
+For the quote form of the include directive, the directory of the current
+file is searched first.
+
+@item
+For the quote form of the include directive, the directories specified
+by @option{-iquote} options are searched in left-to-right order,
+as they appear on the command line.
+
+@item
+Directories specified with @option{-I} options are scanned in
+left-to-right order.
-This can be used to override a system header
+@item
+Directories specified with @option{-isystem} options are scanned in
+left-to-right order.
+
+@item
+Standard system directories are scanned.
+
+@item
+Directories specified with @option{-idirafter} options are scanned in
+left-to-right order.
+@end enumerate
+
+You can use @option{-I} to override a system header
file, substituting your own version, since these directories are
-searched before the system header file directories. However, you should
+searched before the standard system header file directories.
+However, you should
not use this option to add directories that contain vendor-supplied
-system header files (use @option{-isystem} for that).
+system header files; use @option{-isystem} for that.
+
+The @option{-isystem} and @option{-idirafter} options also mark the directory
+as a system directory, so that it gets the same special treatment that
+is applied to the standard system directories.
+@ifset cppmanual
+@xref{System Headers}.
+@end ifset
If a standard system include directory, or a directory specified with
@option{-isystem}, is also specified with @option{-I}, the @option{-I}
option is ignored. The directory is still 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 @code{include_next} directive are not inadvertently changed.
+the ordering for the @code{#include_next} directive are not inadvertently
+changed.
If you really need to change the search order for system directories,
use the @option{-nostdinc} and/or @option{-isystem} options.
@ifset cppmanual
@xref{System Headers}.
@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -iquote @var{dir}
-@opindex iquote
-Search @var{dir} only for header files requested with
-@code{@w{#include "@var{file}"}}; they are not searched for
-@code{@w{#include <@var{file}>}}, before all directories specified by
-@option{-I} and before the standard system directories.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -isystem @var{dir}
-@opindex isystem
-Search @var{dir} for header files, after all directories specified by
-@option{-I} but before the standard system directories. Mark it
-as a system directory, so that it gets the same special treatment as
-is applied to the standard system directories.
-@ifset cppmanual
-@xref{System Headers}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
@item -I-
@opindex I-
Split the include path.
@xref{Search Path}.
@end ifset
-@item -idirafter @var{dir}
-@opindex idirafter
-Search @var{dir} for header files, but do it @emph{after} all
-directories specified with @option{-I} and the standard system directories
-have been exhausted. @var{dir} is treated as a system include directory.
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
@item -iprefix @var{prefix}
@opindex iprefix
Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
@item -nostdinc
@opindex nostdinc
Do not search the standard system directories for header files.
-Only the directories you have specified with @option{-I} options
-(and the directory of the current file, if appropriate) are searched.
+Only the directories explicitly specified with @option{-I},
+@option{-iquote}, @option{-isystem}, and/or @option{-idirafter}
+options (and the directory of the current file, if appropriate)
+are searched.
@item -nostdinc++
@opindex nostdinc++
@item -D @var{name}=@var{definition}
The contents of @var{definition} are tokenized and processed as if
they appeared during translation phase three in a @samp{#define}
-directive. In particular, the definition will be truncated by
+directive. In particular, the definition is truncated by
embedded newline characters.
If you are invoking the preprocessor from a shell or shell-like
If you wish to define a function-like macro on the command line, write
its argument list with surrounding parentheses before the equals sign
-(if any). Parentheses are meaningful to most shells, so you will need
-to quote the option. With @command{sh} and @command{csh},
+(if any). Parentheses are meaningful to most shells, so you should
+quote the option. With @command{sh} and @command{csh},
@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
@option{-D} and @option{-U} options are processed in the order they
rules you should explicitly specify the dependency output file with
@option{-MF}, or use an environment variable like
@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output
-will still be sent to the regular output stream as normal.
+is still sent to the regular output stream as normal.
Passing @option{-M} to the driver implies @option{-E}, and suppresses
warnings with an implicit @option{-w}.
This implies that the choice of angle brackets or double quotes in an
@samp{#include} directive does not in itself determine whether that
-header will appear in @option{-MM} dependency output. This is a
-slight change in semantics from GCC versions 3.0 and earlier.
+header appears in @option{-MM} dependency output.
@anchor{dashMF}
@item -MF @var{file}
@opindex MF
When used with @option{-M} or @option{-MM}, specifies a
file to write the dependencies to. If no @option{-MF} switch is given
-the preprocessor sends the rules to the same place it would have sent
+the preprocessor sends the rules to the same place it would send
preprocessed output.
When used with the driver options @option{-MD} or @option{-MMD},
directory components and any file suffix such as @samp{.c}, and
appends the platform's usual object suffix. The result is the target.
-An @option{-MT} option will set the target to be exactly the string you
+An @option{-MT} option sets the target to be exactly the string you
specify. If you want multiple targets, you can specify them as a single
argument to @option{-MT}, or use multiple @option{-MT} options.
memory. The @var{level} parameter can be used to choose the level of
precision of token location tracking thus decreasing the memory
consumption if necessary. Value @samp{0} of @var{level} de-activates
-this option just as if no @option{-ftrack-macro-expansion} was present
-on the command line. Value @samp{1} tracks tokens locations in a
+this option. Value @samp{1} tracks tokens locations in a
degraded mode for the sake of minimal memory overhead. In this mode
all tokens resulting from the expansion of an argument of a
function-like macro have the same location. Value @samp{2} tracks
@item -fpch-deps
@opindex fpch-deps
When using precompiled headers (@pxref{Precompiled Headers}), this flag
-will cause the dependency-output flags to also list the files from the
-precompiled header's dependencies. If not specified only the
-precompiled header would be listed and not the files that were used to
-create it because those files are not consulted when a precompiled
+causes the dependency-output flags to also list the files from the
+precompiled header's dependencies. If not specified, only the
+precompiled header are listed and not the files that were used to
+create it, because those files are not consulted when a precompiled
header is used.
@item -fpch-preprocess
@item -fworking-directory
@opindex fworking-directory
@opindex fno-working-directory
-Enable generation of linemarkers in the preprocessor output that will
+Enable generation of linemarkers in the preprocessor output that
let the compiler know the current working directory at the time of
-preprocessing. When this option is enabled, the preprocessor will
-emit, after the initial linemarker, a second linemarker with the
-current working directory followed by two slashes. GCC will use this
+preprocessing. When this option is enabled, the preprocessor
+emits, after the initial linemarker, a second linemarker with the
+current working directory followed by two slashes. GCC uses this
directory, when it's present in the preprocessed input, as the
directory emitted as the current working directory in some debugging
information formats. This option is implicitly enabled if debugging
source line, since the first token on the line is no longer a @samp{#}.
@item -CC
+@opindex CC
Do not discard comments, including during macro expansion. This is
like @option{-C}, except that comments contained within macros are
also passed through to the output file where the macro is expanded.
@end smallexample
@noindent
-will show all the predefined macros.
+shows all the predefined macros.
@ifclear cppmanual
If you use @option{-dM} without the @option{-E} option, @option{-dM} is
@item -fdebug-cpp
@opindex fdebug-cpp
-This option is only useful for debugging GCC. When used with
-@option{-E}, dumps debugging information about location maps. Every
+This option is only useful for debugging GCC. When used from CPP or with
+@option{-E}, it dumps debugging information about location maps. Every
token in the output is preceded by the dump of the map its location
-belongs to. The dump of the map holding the location of a token would
-be:
-@smallexample
-@{@samp{P}:@file{/file/path};@samp{F}:@file{/includer/path};@samp{L}:@var{line_num};@samp{C}:@var{col_num};@samp{S}:@var{system_header_p};@samp{M}:@var{map_address};@samp{E}:@var{macro_expansion_p},@samp{loc}:@var{location}@}
-@end smallexample
+belongs to.
-When used without @option{-E}, this option has no effect.
+When used from GCC without @option{-E}, this option has no effect.
@opindex Wunused-macros
Warn about macros defined in the main file that are unused. A macro
is @dfn{used} if it is expanded or tested for existence at least once.
-The preprocessor will also warn if the macro has not been used at the
+The preprocessor also warns if the macro has not been used at the
time it is redefined or undefined.
Built-in macros, macros defined on the command line, and macros
defined in include files are not warned about.
@emph{Note:} If a macro is actually used, but only used in skipped
-conditional blocks, then CPP will report it as unused. To avoid the
+conditional blocks, then the preprocessor reports it as unused. To avoid the
warning in such a case, you might improve the scope of the macro's
definition by, for example, moving it into the first skipped block.
Alternatively, you could provide a dummy use with something like:
@opindex Wno-endif-labels
@opindex Wendif-labels
Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
-This usually happens in code of the form
+This sometimes happens in older programs with code of the form
@smallexample
#if FOO
@end smallexample
@noindent
-The second and third @code{FOO} should be in comments, but often are not
-in older programs. This warning is on by default.
-
+The second and third @code{FOO} should be in comments.
+This warning is on by default.
projects / gcc.git / commitdiff