From: Sandra Loosemore Date: Mon, 26 Dec 2016 00:31:02 +0000 (-0500) Subject: cpp.texi (Invocation): Revise to indicate that GCC driver options are only documented... X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=71585576bc1de428f4741b4cb6cc7d5eebea4166;p=gcc.git cpp.texi (Invocation): Revise to indicate that GCC driver options are only documented in the GCC manual. 2016-12-25 Sandra Loosemore gcc/ * doc/cpp.texi (Invocation): Revise to indicate that GCC driver options are only documented in the GCC manual. * doc/cppopts.texi: Delete documentation of GCC driver options -o, -Wall, -Wtraditional, -Werror, -Wsystem-headers, -w, -pedantic, -pedantic-errors, -std=, -ansi, --help, --target-help, -v, -version. Update -Wcomment, -Wtrigraphs, -Wundef, -Wexpansion-to-defined, -Wno-endif-labels, -traditional, -traditional-cpp, -trigraphs to merge text previously in GCC manual. * doc/invoke.texi (Option Summary): Move -trigraphs, -traditional, and -traditional-cpp from C dialect options to preprocessor options. (C Dialect Options): Likewise. (Warning Options): Delete documentation of -Wcomment, -Wtrigraphs, -Wexpansion-to-defined, -Wundef, and -Wno-endif-labels. From-SVN: r243923 --- diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 6947477ea53..412a6e0f19b 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,19 @@ +2016-12-25 Sandra Loosemore + + * doc/cpp.texi (Invocation): Revise to indicate that GCC driver + options are only documented in the GCC manual. + * doc/cppopts.texi: Delete documentation of GCC driver options + -o, -Wall, -Wtraditional, -Werror, -Wsystem-headers, -w, + -pedantic, -pedantic-errors, -std=, -ansi, --help, --target-help, + -v, -version. Update -Wcomment, -Wtrigraphs, -Wundef, + -Wexpansion-to-defined, -Wno-endif-labels, -traditional, + -traditional-cpp, -trigraphs to merge text previously in GCC manual. + * doc/invoke.texi (Option Summary): Move -trigraphs, -traditional, + and -traditional-cpp from C dialect options to preprocessor options. + (C Dialect Options): Likewise. + (Warning Options): Delete documentation of -Wcomment, -Wtrigraphs, + -Wexpansion-to-defined, -Wundef, and -Wno-endif-labels. + 2016-12-24 Richard Sandiford * tree-core.h (tree_base): Document the meaning of public_flag diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index 7348448f497..8810b1ea774 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -4285,51 +4285,54 @@ You can also make or cancel assertions using command-line options. @cindex invocation @cindex command line -Most often when you use the C preprocessor you will not have to invoke it -explicitly: the C compiler will do so automatically. However, the -preprocessor is sometimes useful on its own. All the options listed -here are also acceptable to the C compiler and have the same meaning, -except that the C compiler has different rules for specifying the output -file. - -@emph{Note:} Whether you use the preprocessor by way of @command{gcc} -or @command{cpp}, the @dfn{compiler driver} is run first. This -program's purpose is to translate your command into invocations of the -programs that do the actual work. Their command-line interfaces are -similar but not identical to the documented interface, and may change -without notice. +Most often when you use the C preprocessor you do not have to invoke it +explicitly: the C compiler does so automatically. However, the +preprocessor is sometimes useful on its own. You can invoke the +preprocessor either with the @command{cpp} command, or via @command{gcc -E}. +In GCC, the preprocessor is actually integrated with the compiler +rather than a separate program, and both of these commands invoke +GCC and tell it to stop after the preprocessing phase. + +The @command {cpp} options listed here are also accepted by +@command{gcc} and have the same meaning. Likewise the @command{cpp} +command accepts all the usual @command{gcc} driver options, although those +pertaining to compilation phases after preprocessing are ignored. + +Only options specific to preprocessing behavior are documented here. +Refer to the GCC manual for full documentation of other driver options. @ignore @c man begin SYNOPSIS cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}] - [@option{-W}@var{warn}@dots{}] [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] [@option{-MP}] [@option{-MQ} @var{target}@dots{}] [@option{-MT} @var{target}@dots{}] - [@option{-P}] [@option{-fno-working-directory}] - [@option{-x} @var{language}] [@option{-std=}@var{standard}] - @var{infile} @var{outfile} + @var{infile} [[@option{-o}] @var{outfile}] -Only the most useful options are listed here; see below for the remainder. +Only the most useful options are given above; see below for a more +complete list of preprocessor-specific options. +In addition, @command{cpp} accepts most @command{gcc} driver options, which +are not listed here. Refer to the GCC documentation for details. @c man end @c man begin SEEALSO gpl(7), gfdl(7), fsf-funding(7), -gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and -@file{binutils}. +gcc(1), and the Info entries for @file{cpp} and @file{gcc}. @c man end @end ignore @c man begin OPTIONS -The C preprocessor expects two file names as arguments, @var{infile} and +The @command{cpp} command expects two file names as arguments, @var{infile} and @var{outfile}. The preprocessor reads @var{infile} together with any other files it specifies with @samp{#include}. All the output generated by the combined input files is written in @var{outfile}. Either @var{infile} or @var{outfile} may be @option{-}, which as @var{infile} means to read from standard input and as @var{outfile} -means to write to standard output. Also, if either file is omitted, it +means to write to standard output. If either file is omitted, it means the same as if @option{-} had been specified for that file. +You can also use the @option{-o @var{outfile}} option to specify the +output file. Unless otherwise noted, or the option ends in @samp{=}, all options which take an argument may have that argument appear either immediately @@ -4343,7 +4346,10 @@ options may @emph{not} be grouped: @option{-dM} is very different from @w{@samp{-d -M}}. @cindex options + +@table @gcctabopt @include cppopts.texi +@end table @c man end @node Environment Variables diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi index e349555909c..567a74813b7 100644 --- a/gcc/doc/cppopts.texi +++ b/gcc/doc/cppopts.texi @@ -9,7 +9,6 @@ @c If this file is included with the flag ``cppmanual'' set, it is @c formatted for inclusion in the CPP manual; otherwise the main GCC manual. -@table @gcctabopt @item -D @var{name} @opindex D Predefine @var{name} as a macro, with definition @code{1}. @@ -67,64 +66,38 @@ of system headers are not defeated If @var{dir} begins with @code{=}, then the @code{=} will be replaced by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. -@item -o @var{file} -@opindex o -Write output to @var{file}. This is the same as specifying @var{file} -as the second non-option argument to @command{cpp}. @command{gcc} has a -different interpretation of a second non-option argument, so you must -use @option{-o} to specify the output file. - -@item -Wall -@opindex Wall -Turns on all optional warnings which are desirable for normal code. -At present this is @option{-Wcomment}, @option{-Wtrigraphs}, -@option{-Wmultichar} and a warning about integer promotion causing a -change of sign in @code{#if} expressions. Note that many of the -preprocessor's warnings are on by default and have no options to -control them. - @item -Wcomment @itemx -Wcomments @opindex Wcomment @opindex Wcomments Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} comment, or whenever a backslash-newline appears in a @samp{//} comment. -(Both forms have the same effect.) +This warning is enabled by @option{-Wall}. @item -Wtrigraphs @opindex Wtrigraphs @anchor{Wtrigraphs} -Most trigraphs in comments cannot affect the meaning of the program. -However, a trigraph that would form an escaped newline (@samp{??/} at -the end of a line) can, by changing where the comment begins or ends. -Therefore, only trigraphs that would form escaped newlines produce -warnings inside a comment. +Warn if any trigraphs are encountered that might change the meaning of +the program. Trigraphs within comments are not warned about, +except those that would form escaped newlines. This option is implied by @option{-Wall}. If @option{-Wall} is not given, this option is still enabled unless trigraphs are enabled. To get trigraph conversion without warnings, but get the other @option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}. -@item -Wtraditional -@opindex Wtraditional -Warn about certain constructs that behave differently in traditional and -ISO C@. Also warn about ISO C constructs that have no traditional C -equivalent, and problematic constructs which should be avoided. -@ifset cppmanual -@xref{Traditional Mode}. -@end ifset - @item -Wundef @opindex Wundef -Warn whenever an identifier which is not a macro is encountered in an -@samp{#if} directive, outside of @samp{defined}. Such identifiers are -replaced with zero. +@opindex Wno-undef +Warn if an undefined identifier is evaluated in an @code{#if} directive. +Such identifiers are replaced with zero. @item -Wexpansion-to-defined @opindex Wexpansion-to-defined Warn whenever @samp{defined} is encountered in the expansion of a macro (including the case where the macro is expanded by an @samp{#if} directive). Such usage is not portable. +This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}. @item -Wunused-macros @opindex Wunused-macros @@ -147,9 +120,10 @@ Alternatively, you could provide a dummy use with something like: #endif @end smallexample -@item -Wendif-labels +@item -Wno-endif-labels +@opindex Wno-endif-labels @opindex Wendif-labels -Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. +Do not warn whenever an @code{#else} or an @code{#endif} are followed by text. This usually happens in code of the form @smallexample @@ -164,33 +138,6 @@ This usually happens in code of the form The second and third @code{FOO} should be in comments, but often are not in older programs. This warning is on by default. -@item -Werror -@opindex Werror -Make all warnings into hard errors. Source code which triggers warnings -will be rejected. - -@item -Wsystem-headers -@opindex Wsystem-headers -Issue warnings for code in system headers. These are normally unhelpful -in finding bugs in your own code, therefore suppressed. If you are -responsible for the system library, you may want to see them. - -@item -w -@opindex w -Suppress all warnings, including those which GNU CPP issues by default. - -@item -pedantic -@opindex pedantic -Issue all the mandatory diagnostics listed in the C standard. Some of -them are left out by default, since they trigger frequently on harmless -code. - -@item -pedantic-errors -@opindex pedantic-errors -Issue all the mandatory diagnostics, and make all mandatory diagnostics -into errors. This includes mandatory diagnostics that GCC issues -without @samp{-pedantic} but treats as warnings. - @item -M @opindex M @cindex @command{make} @@ -369,60 +316,6 @@ which selected both the language and the standards conformance level. This option has been removed, because it conflicts with the @option{-l} option. -@item -std=@var{standard} -@itemx -ansi -@opindex ansi -@opindex std= -Specify the standard to which the code should conform. Currently CPP -knows about C and C++ standards; others may be added in the future. - -@var{standard} -may be one of: -@table @code -@item c90 -@itemx c89 -@itemx iso9899:1990 -The ISO C standard from 1990. @samp{c90} is the customary shorthand for -this version of the standard. - -The @option{-ansi} option is equivalent to @option{-std=c90}. - -@item iso9899:199409 -The 1990 C standard, as amended in 1994. - -@item iso9899:1999 -@itemx c99 -@itemx iso9899:199x -@itemx c9x -The revised ISO C standard, published in December 1999. Before -publication, this was known as C9X@. - -@item iso9899:2011 -@itemx c11 -@itemx c1x -The revised ISO C standard, published in December 2011. Before -publication, this was known as C1X@. - -@item gnu90 -@itemx gnu89 -The 1990 C standard plus GNU extensions. This is the default. - -@item gnu99 -@itemx gnu9x -The 1999 C standard plus GNU extensions. - -@item gnu11 -@itemx gnu1x -The 2011 C standard plus GNU extensions. - -@item c++98 -The 1998 ISO C++ standard plus amendments. - -@item gnu++98 -The same as @option{-std=c++98} plus GNU extensions. This is the -default for C++ code. -@end table - @item -I- @opindex I- Split the include path. Any directories specified with @option{-I} @@ -714,9 +607,11 @@ touch foo.h; cpp -dM foo.h @noindent will show all the predefined macros. +@ifclear cppmanual If you use @option{-dM} without the @option{-E} option, @option{-dM} is interpreted as a synonym for @option{-fdump-rtl-mach}. @xref{Developer Options, , ,gcc}. +@end ifclear @item D @opindex dD @@ -778,28 +673,38 @@ the source line. The @option{-CC} option is generally used to support lint comments. -@item -traditional-cpp +@cindex traditional C language +@cindex C language, traditional +@item -traditional +@itemx -traditional-cpp @opindex traditional-cpp -Try to imitate the behavior of old-fashioned C preprocessors, as +@opindex traditional + +Try to imitate the behavior of pre-standard C preprocessors, as opposed to ISO C preprocessors. @ifset cppmanual @xref{Traditional Mode}. @end ifset +@ifclear cppmanual +See the GNU CPP manual for details. +@end ifclear + +Note that GCC does not otherwise attempt to emulate a pre-standard +C compiler, and these options are only supported with the @option{-E} +switch, or when invoking CPP explicitly. @item -trigraphs @opindex trigraphs -Process trigraph sequences. -@ifset cppmanual -@xref{Initial processing}. -@end ifset -@ifclear cppmanual +Support ISO C trigraphs. These are three-character sequences, all starting with @samp{??}, that are defined by ISO C to stand for single characters. For example, @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character -constant for a newline. By default, GCC ignores trigraphs, but in -standard-conforming modes it converts them. See the @option{-std} and -@option{-ansi} options. +constant for a newline. +@ifset cppmanual +@xref{Initial processing}. +@end ifset +@ifclear cppmanual The nine trigraphs and their replacements are @smallexample @@ -808,23 +713,15 @@ Replacement: [ ] @{ @} # \ ^ | ~ @end smallexample @end ifclear +By default, GCC ignores trigraphs, but in +standard-conforming modes it converts them. See the @option{-std} and +@option{-ansi} options. + @item -remap @opindex remap Enable special code to work around file systems which only permit very short file names, such as MS-DOS@. -@item --help -@itemx --target-help -@opindex help -@opindex target-help -Print text describing all the command-line options instead of -preprocessing anything. - -@item -v -@opindex v -Verbose mode. Print out GNU CPP's version number at the beginning of -execution, and report the final form of the include path. - @item -H @opindex H Print the name of each header file used, in addition to other normal @@ -833,9 +730,3 @@ activities. Each name is indented to show how deep in the printed, even if they are found to be invalid; an invalid precompiled header file is printed with @samp{...x} and a valid one with @samp{...!} . -@item -version -@itemx --version -@opindex version -Print out GNU CPP's version number. With one dash, proceed to -preprocess as normal. With two dashes, exit immediately. -@end table diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 1096254085f..878d522181f 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -185,8 +185,7 @@ in the following sections. -fms-extensions -fplan9-extensions -fsso-struct=@var{endianness} -fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol -fsigned-bitfields -fsigned-char @gol --funsigned-bitfields -funsigned-char @gol --trigraphs -traditional -traditional-cpp} +-funsigned-bitfields -funsigned-char} @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @@ -472,7 +471,8 @@ Objective-C and Objective-C++ Dialects}. -imultilib @var{dir} -isysroot @var{dir} @gol -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol -P -fdebug-cpp -ftrack-macro-expansion -fworking-directory @gol --remap -trigraphs -undef -U@var{macro} @gol +-remap -traditional -traditional-cpp -trigraphs @gol +-undef -U@var{macro} @gol -Wp,@var{option} -Xpreprocessor @var{option} -no-integrated-cpp} @item Assembler Option @@ -2101,22 +2101,6 @@ fields declared using a typedef. @xref{Unnamed Fields,,Unnamed struct/union fields within structs/unions}, for details. This is only supported for C, not C++. -@item -trigraphs -@opindex trigraphs -Support ISO C trigraphs. The @option{-ansi} option (and @option{-std} -options for strict ISO C conformance) implies @option{-trigraphs}. - -@cindex traditional C language -@cindex C language, traditional -@item -traditional -@itemx -traditional-cpp -@opindex traditional-cpp -@opindex traditional -Formerly, these options caused GCC to attempt to emulate a pre-standard -C compiler. They are now only supported with the @option{-E} switch. -The preprocessor continues to support a pre-standard mode. See the GNU -CPP manual for details. - @item -fcond-mismatch @opindex fcond-mismatch Allow conditional expressions with mismatched types in the second and @@ -3838,13 +3822,6 @@ of error, as programmers often forget that this type is signed on some machines. This warning is enabled by @option{-Wall}. -@item -Wcomment -@opindex Wcomment -@opindex Wno-comment -Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} -comment, or whenever a Backslash-Newline appears in a @samp{//} comment. -This warning is enabled by @option{-Wall}. - @item -Wno-coverage-mismatch @opindex Wno-coverage-mismatch Warn if feedback profiles do not match when using the @@ -4610,13 +4587,6 @@ This warning is enabled by default for C and C++ programs. Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch} built-in functions are used. These functions changed semantics in GCC 4.4. -@item -Wtrigraphs -@opindex Wtrigraphs -@opindex Wno-trigraphs -Warn if any trigraphs are encountered that might change the meaning of -the program (trigraphs within comments are not warned about). -This warning is enabled by @option{-Wall}. - @item -Wunused-but-set-parameter @opindex Wunused-but-set-parameter @opindex Wno-unused-but-set-parameter @@ -5458,21 +5428,6 @@ Warn when a declaration is found after a statement in a block. This construct, known from C++, was introduced with ISO C99 and is by default allowed in GCC@. It is not supported by ISO C90. @xref{Mixed Declarations}. -@item -Wexpansion-to-defined -@opindex Wexpansion-to-defined -Warn whenever @samp{defined} is encountered in the expansion of a macro. -This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}. - -@item -Wundef -@opindex Wundef -@opindex Wno-undef -Warn if an undefined identifier is evaluated in an @code{#if} directive. - -@item -Wno-endif-labels -@opindex Wno-endif-labels -@opindex Wendif-labels -Do not warn whenever an @code{#else} or an @code{#endif} are followed by text. - @item -Wshadow @opindex Wshadow @opindex Wno-shadow @@ -11371,9 +11326,9 @@ This option may be useful in conjunction with the @option{-B} or @option{-wrapper} options to specify an alternate preprocessor or perform additional processing of the program source between normal preprocessing and compilation. -@end table @include cppopts.texi +@end table @node Assembler Options @section Passing Options to the Assembler