OpenE2K
/
gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

cppdiropts.texi: Merge documentation of -I, -iquote, -isystem, and -idirafter. 

2017-01-07  Sandra Loosemore  <sandra@codesourcery.com>

	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
This commit is contained in:
Sandra Loosemore 2017-01-07 17:37:55 -05:00 committed by Sandra Loosemore
parent 5ccf1d8d10
commit ec85a97831
4 changed files with 99 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
gcc/ChangeLog
View File

@ -1,3 +1,12 @@
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

108
gcc/doc/cppdiropts.texi
View File

@ -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}.
This can be used to override a system header
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.
@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++

49
gcc/doc/cppopts.texi
View File

@ -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.

11
gcc/doc/cppwarnopts.texi
View File

@ -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.