From ec85a97831b1818e65ef2797781c27a511f68c24 Mon Sep 17 00:00:00 2001 From: Sandra Loosemore Date: Sat, 7 Jan 2017 17:37:55 -0500 Subject: [PATCH] cppdiropts.texi: Merge documentation of -I, -iquote, -isystem, and -idirafter. 2017-01-07 Sandra Loosemore gcc/ * 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. From-SVN: r244200 --- gcc/ChangeLog | 9 ++++ gcc/doc/cppdiropts.texi | 108 +++++++++++++++++++++++---------------- gcc/doc/cppopts.texi | 49 ++++++++---------- gcc/doc/cppwarnopts.texi | 11 ++-- 4 files changed, 99 insertions(+), 78 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 38b6102f3f7..c35032cd21f 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,12 @@ +2017-01-07 Sandra Loosemore + + * 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 PR c++/72803 diff --git a/gcc/doc/cppdiropts.texi b/gcc/doc/cppdiropts.texi index e28c2f8758b..1f72649937c 100644 --- a/gcc/doc/cppdiropts.texi +++ b/gcc/doc/cppdiropts.texi @@ -10,61 +10,85 @@ @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. @@ -86,14 +110,6 @@ file directory as the first search directory for @code{@w{#include @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} @@ -124,8 +140,10 @@ target-specific C++ headers. @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++ diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi index 071e50e4771..44e714940e1 100644 --- a/gcc/doc/cppopts.texi +++ b/gcc/doc/cppopts.texi @@ -16,7 +16,7 @@ Predefine @var{name} as a macro, with definition @code{1}. @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 @@ -25,8 +25,8 @@ characters such as spaces that have a meaning in the shell syntax. 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 @@ -92,7 +92,7 @@ This option does not suppress the preprocessor's debug output, such as 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}. @@ -105,15 +105,14 @@ directly or indirectly, from such a header. 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}, @@ -154,7 +153,7 @@ default CPP takes the name of the main input file, deletes any 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. @@ -269,8 +268,7 @@ option makes the preprocessor and the compiler consume more 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 @@ -312,10 +310,10 @@ supported by the system's @code{iconv} library routine. @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 @@ -340,11 +338,11 @@ current directory. @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 @@ -380,6 +378,7 @@ directive line have the effect of turning that line into an ordinary 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. @@ -480,7 +479,7 @@ touch foo.h; cpp -dM foo.h @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 @@ -515,14 +514,10 @@ undefined at the time. @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. diff --git a/gcc/doc/cppwarnopts.texi b/gcc/doc/cppwarnopts.texi index 0dc2a1efebd..35761e38592 100644 --- a/gcc/doc/cppwarnopts.texi +++ b/gcc/doc/cppwarnopts.texi @@ -46,14 +46,14 @@ This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}. @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: @@ -67,7 +67,7 @@ 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 @@ -78,6 +78,5 @@ This usually happens in code of the form @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. -- 2.30.2