From patchwork Fri Dec 30 21:29:14 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 89407 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp6611834qgi; Fri, 30 Dec 2016 13:29:47 -0800 (PST) X-Received: by 10.98.157.199 with SMTP id a68mr30444360pfk.129.1483133387453; Fri, 30 Dec 2016 13:29:47 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id w12si58120784pfi.107.2016.12.30.13.29.47 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 30 Dec 2016 13:29:47 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-445140-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-445140-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-445140-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=uEAshtnsEYHTMv1GKg6kA6IsANCf+64xI/WIFwqMw3djMEmL6C zgTZ2ko2zeEGcIyC5fcaSLvlzu2dFK7V7eTdRHk9/XYdpVOpPkYFGfkQdOz4aGVb p7U+lr09Qn2C06eih5WGOVF3g5QSDaeRZo8Ww8fopv7+MoeOm4c6WzLMs= 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=vv41ub9+tI38VNP7m/1aBUI76Eo=; b=gJZ3xG4b2FghldgYTFK/ 4cEdNEdwDy3s8cX9FMcsvP65b1XUVGZFCUO/6Dngm8uNWwVI09L18HVCXxyN1Lui XgtpoNJEAJpPMzEQf/M2BodJ9qIr521HIVtf4k4VZBXsFEnMJqSIcqHwxtpvyEcb BC52RNe2Cq5zwFHWDayzUMY= Received: (qmail 20286 invoked by alias); 30 Dec 2016 21:29:34 -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 20262 invoked by uid 89); 30 Dec 2016 21:29:32 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.6 required=5.0 tests=AWL, BAYES_50, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=ham version=3.3.2 spammy=Preprocessor, xref, @xref, ifclear 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; Fri, 30 Dec 2016 21:29:22 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtp id 1cN4jn-0007jH-4t from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Fri, 30 Dec 2016 13:29:19 -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; Fri, 30 Dec 2016 13:29:16 -0800 To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [doc, committed] reorder entries in cppopts.texi Message-ID: <5866D1AA.9040708@codesourcery.com> Date: Fri, 30 Dec 2016 14:29:14 -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) I've checked in the attached patch to reorder entries in cppopts.texi. I put the most-commonly-used options (e.g. -D and -U) first, and the options for debugging cpp last, and tried to group the things in between a little better. There's no change to actual content here, just the ordering. -Sandra Index: gcc/doc/cppopts.texi =================================================================== --- gcc/doc/cppopts.texi (revision 243983) +++ gcc/doc/cppopts.texi (working copy) @@ -39,6 +39,28 @@ are given on the command line. All @opt Cancel any previous definition of @var{name}, either built in or provided with a @option{-D} option. +@item -include @var{file} +@opindex include +Process @var{file} as if @code{#include "file"} appeared as the first +line of the primary source file. However, the first directory searched +for @var{file} is the preprocessor's working directory @emph{instead of} +the directory containing the main source file. If not found there, it +is searched for in the remainder of the @code{#include "@dots{}"} search +chain as normal. + +If multiple @option{-include} options are given, the files are included +in the order they appear on the command line. + +@item -imacros @var{file} +@opindex imacros +Exactly like @option{-include}, except that any output produced by +scanning @var{file} is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. + +All files specified by @option{-imacros} are processed before all files +specified by @option{-include}. + @item -undef @opindex undef Do not predefine any system-specific or GCC-specific macros. The @@ -177,57 +199,21 @@ a dependency output file as a side-effec Like @option{-MD} except mention only user header files, not system header files. -@ifclear cppmanual -@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 -header is used. - -@item -fpch-preprocess -@opindex fpch-preprocess -This option allows use of a precompiled header (@pxref{Precompiled -Headers}) together with @option{-E}. It inserts a special @code{#pragma}, -@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark -the place where the precompiled header was found, and its @var{filename}. -When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} -and loads the PCH@. +@item -fpreprocessed +@opindex fpreprocessed +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with @option{-C} to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. -This option is off by default, because the resulting preprocessed output -is only really suitable as input to GCC@. It is switched on by +@option{-fpreprocessed} is implicit if the input file has one of the +extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the +extensions that GCC uses for preprocessed files created by @option{-save-temps}. -You should not write this @code{#pragma} in your own code, but it is -safe to edit the filename if the PCH file is available in a different -location. The filename may be absolute or it may be relative to GCC's -current directory. -@end ifclear - -@item -include @var{file} -@opindex include -Process @var{file} as if @code{#include "file"} appeared as the first -line of the primary source file. However, the first directory searched -for @var{file} is the preprocessor's working directory @emph{instead of} -the directory containing the main source file. If not found there, it -is searched for in the remainder of the @code{#include "@dots{}"} search -chain as normal. - -If multiple @option{-include} options are given, the files are included -in the order they appear on the command line. - -@item -imacros @var{file} -@opindex imacros -Exactly like @option{-include}, except that any output produced by -scanning @var{file} is thrown away. Macros it defines remain defined. -This allows you to acquire all the macros from a header without also -processing its declarations. - -All files specified by @option{-imacros} are processed before all files -specified by @option{-include}. - @item -fdirectives-only @opindex fdirectives-only When preprocessing, handle directives, but do not expand macros. @@ -267,21 +253,6 @@ enabled by default for C99 (and later C @opindex fno-canonical-system-headers When preprocessing, do not shorten system header paths with canonicalization. -@item -fpreprocessed -@opindex fpreprocessed -Indicate to the preprocessor that the input file has already been -preprocessed. This suppresses things like macro expansion, trigraph -conversion, escaped newline splicing, and processing of most directives. -The preprocessor still recognizes and removes comments, so that you can -pass a file preprocessed with @option{-C} to the compiler without -problems. In this mode the integrated preprocessor is little more than -a tokenizer for the front ends. - -@option{-fpreprocessed} is implicit if the input file has one of the -extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the -extensions that GCC uses for preprocessed files created by -@option{-save-temps}. - @item -ftabstop=@var{width} @opindex ftabstop Set the distance between tab stops. This helps the preprocessor report @@ -289,19 +260,6 @@ correct column numbers in warnings or er line. If the value is less than 1 or greater than 100, the option is ignored. The default is 8. -@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 -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 - -When used without @option{-E}, this option has no effect. - @item -ftrack-macro-expansion@r{[}=@var{level}@r{]} @opindex ftrack-macro-expansion Track locations of tokens across macro expansions. This allows the @@ -350,6 +308,35 @@ or this command-line option. Currently precedence if there's a conflict. @var{charset} can be any encoding supported by the system's @code{iconv} library routine. +@ifclear cppmanual +@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 +header is used. + +@item -fpch-preprocess +@opindex fpch-preprocess +This option allows use of a precompiled header (@pxref{Precompiled +Headers}) together with @option{-E}. It inserts a special @code{#pragma}, +@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark +the place where the precompiled header was found, and its @var{filename}. +When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} +and loads the PCH@. + +This option is off by default, because the resulting preprocessed output +is only really suitable as input to GCC@. It is switched on by +@option{-save-temps}. + +You should not write this @code{#pragma} in your own code, but it is +safe to edit the filename if the PCH file is available in a different +location. The filename may be absolute or it may be relative to GCC's +current directory. +@end ifclear + @item -fworking-directory @opindex fworking-directory @opindex fno-working-directory @@ -380,70 +367,6 @@ it does not use shell special characters Cancel an assertion with the predicate @var{predicate} and answer @var{answer}. -@item -dCHARS -@var{CHARS} is a sequence of one or more of the following characters, -and must not be preceded by a space. Other characters are interpreted -by the compiler proper, or reserved for future versions of GCC, and so -are silently ignored. If you specify characters whose behavior -conflicts, the result is undefined. - -@table @samp -@item M -@opindex dM -Instead of the normal output, generate a list of @samp{#define} -directives for all the macros defined during the execution of the -preprocessor, including predefined macros. This gives you a way of -finding out what is predefined in your version of the preprocessor. -Assuming you have no file @file{foo.h}, the command - -@smallexample -touch foo.h; cpp -dM foo.h -@end smallexample - -@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 -Like @samp{M} except in two respects: it does @emph{not} include the -predefined macros, and it outputs @emph{both} the @samp{#define} -directives and the result of preprocessing. Both kinds of output go to -the standard output file. - -@item N -@opindex dN -Like @samp{D}, but emit only the macro names, not their expansions. - -@item I -@opindex dI -Output @samp{#include} directives in addition to the result of -preprocessing. - -@item U -@opindex dU -Like @samp{D} except that only macros that are expanded, or whose -definedness is tested in preprocessor directives, are output; the -output is delayed until the use or test of the macro; and -@samp{#undef} directives are also output for macros tested but -undefined at the time. -@end table - -@item -P -@opindex P -Inhibit generation of linemarkers in the output from the preprocessor. -This might be useful when running the preprocessor on something that is -not C code, and will be sent to a program which might be confused by the -linemarkers. -@ifset cppmanual -@xref{Preprocessor Output}. -@end ifset - @item -C @opindex C Do not discard comments. All comments are passed through to the output @@ -469,6 +392,16 @@ the source line. The @option{-CC} option is generally used to support lint comments. +@item -P +@opindex P +Inhibit generation of linemarkers in the output from the preprocessor. +This might be useful when running the preprocessor on something that is +not C code, and will be sent to a program which might be confused by the +linemarkers. +@ifset cppmanual +@xref{Preprocessor Output}. +@end ifset + @cindex traditional C language @cindex C language, traditional @item -traditional @@ -526,3 +459,70 @@ 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 -dCHARS +@var{CHARS} is a sequence of one or more of the following characters, +and must not be preceded by a space. Other characters are interpreted +by the compiler proper, or reserved for future versions of GCC, and so +are silently ignored. If you specify characters whose behavior +conflicts, the result is undefined. + +@table @samp +@item M +@opindex dM +Instead of the normal output, generate a list of @samp{#define} +directives for all the macros defined during the execution of the +preprocessor, including predefined macros. This gives you a way of +finding out what is predefined in your version of the preprocessor. +Assuming you have no file @file{foo.h}, the command + +@smallexample +touch foo.h; cpp -dM foo.h +@end smallexample + +@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 +Like @samp{M} except in two respects: it does @emph{not} include the +predefined macros, and it outputs @emph{both} the @samp{#define} +directives and the result of preprocessing. Both kinds of output go to +the standard output file. + +@item N +@opindex dN +Like @samp{D}, but emit only the macro names, not their expansions. + +@item I +@opindex dI +Output @samp{#include} directives in addition to the result of +preprocessing. + +@item U +@opindex dU +Like @samp{D} except that only macros that are expanded, or whose +definedness is tested in preprocessor directives, are output; the +output is delayed until the use or test of the macro; and +@samp{#undef} directives are also output for macros tested but +undefined at the time. +@end table + +@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 +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 + +When used without @option{-E}, this option has no effect. +