From patchwork Mon Dec 26 00:48:47 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 89008 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp4304626qgi; Sun, 25 Dec 2016 16:49:26 -0800 (PST) X-Received: by 10.98.29.74 with SMTP id d71mr14300021pfd.144.1482713366591; Sun, 25 Dec 2016 16:49:26 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id q186si41410439pga.81.2016.12.25.16.49.26 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 25 Dec 2016 16:49:26 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-445039-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org; spf=pass (google.com: domain of gcc-patches-return-445039-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-445039-patch=linaro.org@gcc.gnu.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=eJ3DAwCCYeXN+dcSKHvNsonm+Qhykrp0C7xIUaA+tza10jdEce AG+oh0vMZtpPR8w8dGNeeGfA/+Sk6f7iO4Mr0XFq07okU5FV+Djiy2HXcnUaWJEG OhUh1ah5aGOEqc7FuSuM7wqghyzn3eXJoIYDoJ6M2Tim/gokTxnUYxa/Y= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=pq+5fv+XBsY4lbioCCRDd+CQCi4=; b=nZpfVowfLC2KT6wzoAEk xJF2pf7vLIplB+uTeFexORg2M5H1O+j2mf2+Waa0QGexd/2i/X6wq6RFYs5RWNyr 8cCr3ImeEpYVTi/2dL/jnxWqYyqtHMZyqis6CrReywuHnYnr1OrmdahES172t+xe E4QXVJtwr0Jn0zB3RKs3rQU= Received: (qmail 105053 invoked by alias); 26 Dec 2016 00:49:09 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 104923 invoked by uid 89); 26 Dec 2016 00:49:05 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=2.4 required=5.0 tests=AWL, BAYES_40, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_NONE, SPF_PASS, UNSUBSCRIBE_BODY, URIBL_RED autolearn=no version=3.3.2 spammy=Their, planned, translate, structs X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 26 Dec 2016 00:48:55 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtp id 1cLJTA-0000Fn-4l from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Sun, 25 Dec 2016 16:48:52 -0800 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) with Microsoft SMTP Server (TLS) id 15.0.1210.3; Sun, 25 Dec 2016 16:48:49 -0800 To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [doc, committed] clean up redundant cpp option documentation Message-ID: <586068EF.8030008@codesourcery.com> Date: Sun, 25 Dec 2016 17:48:47 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.5.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-01.mgc.mentorg.com (147.34.90.201) To svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) This patch is part 2 of a series to clean up bit rot in the CPP manual and preprocessor option documentation in the GCC manual. In this installment, I have tossed out redundant copies of documentation of generic GCC driver options from cppopts.texi, and likewise redundant documentation of preprocessor-specific options from invoke.texi, so now options should only be documented in one file or the other. In cases where the two copies of documentation for a preprocessor option said slightly different things, I tried to merge the text. I also rewrote the introduction to the Invocation section of the CPP manual to clarify that "cpp" accepts all the same GCC driver options as "gcc -E", and to read the GCC manual to find out about them. My next planned installment of this series will tidy up the organization of the include-path-related and warning-related preprocessor options, and correct the option summary section in the GCC manual. -Sandra Index: gcc/doc/cpp.texi =================================================================== --- gcc/doc/cpp.texi (revision 243919) +++ gcc/doc/cpp.texi (working copy) @@ -4285,51 +4285,54 @@ You can also make or cancel assertions u @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: @opti @w{@samp{-d -M}}. @cindex options + +@table @gcctabopt @include cppopts.texi +@end table @c man end @node Environment Variables Index: gcc/doc/cppopts.texi =================================================================== --- gcc/doc/cppopts.texi (revision 243919) +++ gcc/doc/cppopts.texi (working copy) @@ -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 #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 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 sh 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 Index: gcc/doc/invoke.texi =================================================================== --- gcc/doc/invoke.texi (revision 243919) +++ gcc/doc/invoke.texi (working copy) @@ -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{ 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 th 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 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 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 @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