From patchwork Wed Jan 4 02:21:34 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 89762 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp8290467qgi; Tue, 3 Jan 2017 18:22:09 -0800 (PST) X-Received: by 10.84.172.131 with SMTP id n3mr138619657plb.5.1483496529588; Tue, 03 Jan 2017 18:22:09 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id l26si45809357pli.179.2017.01.03.18.22.09 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 03 Jan 2017 18:22:09 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-445294-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-445294-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-445294-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=y1VIVdrxy/WLONcchEJJxsR7DECZgGXkVmMaVRL6q5M9bqx9qf NcpGWk2Bw+nV5zrOMMLMHD04nCEh4TX0aT2b/rijFKJT5bVHok3S7Eb5f0BGIFKm YeCW/zVu9zpeGr08MVM7yzSPy3Uf/sgMhVJh4Timqj6dtaCR32R+CSlbM= 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=6apQM05aEJE5UgNw3c2gfvHgS+M=; b=WDi+eH1ZO4fGE3sgxbwR d4g2MHGsAb/gjE1VH0i4y1nVJQ+1icbXWU4n/sUu9fr42n+eLy+yA2tC1Hc/ud9f PIf3yQOb1QmsdQzwE/5t78J2wUVlpLOUqRwq8wFGsLS3Qp7DNT3yvhMjORRO60Yb Rg93KT6WJ72A3rg6T/h86f4= Received: (qmail 118110 invoked by alias); 4 Jan 2017 02:21:52 -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 118099 invoked by uid 89); 4 Jan 2017 02:21:52 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.1 required=5.0 tests=AWL, BAYES_00, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=no version=3.3.2 spammy=brackets, quotes, surrounding, loosemore 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; Wed, 04 Jan 2017 02:21:41 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtp id 1cObCs-0004jp-Qw from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Tue, 03 Jan 2017 18:21:38 -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; Tue, 3 Jan 2017 18:21:35 -0800 To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [doc,rfc] clean up preprocessor option documentation Message-ID: <586C5C2E.4090309@codesourcery.com> Date: Tue, 3 Jan 2017 19:21:34 -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 another installment in my series to clean up the preprocessor documentation. Most of the changes here are just copy-editing for style and markup and fixing/removing obvious bit-rot, but there's also one chunk that I've rewritten completely. The rewrite involves combining the discussion of -I, -iquote, -isystem, and -idirafter to include a coherent explanation of how the preprocessor searches for header files. I think that this belongs in the GCC manual and not just the preprocessor tutorial, and that just discussing the effect of each option in isolation is confusing and doesn't give users the "big picture". The existing documentation may be confusing enough that I ended up getting something wrong in the rewrite, so I'm going to hold off on committing this for a day or two to give others a chance to review and comment first. I'm aware that the tutorial material in cpp.texi also has similar issues, due to newer options not being fully integrated into the older discussion of the behavior of the preprocessor. (E.g., it gives way too much emphasis to the deprecated -I- option.) I'll tackle fixing that with a separate patch. -Sandra Index: gcc/doc/cppdiropts.texi =================================================================== --- gcc/doc/cppdiropts.texi (revision 244009) +++ gcc/doc/cppdiropts.texi (working copy) @@ -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 direc @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++ Index: gcc/doc/cppopts.texi =================================================================== --- gcc/doc/cppopts.texi (revision 244009) +++ gcc/doc/cppopts.texi (working copy) @@ -16,7 +16,7 @@ Predefine @var{name} as a macro, with de @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 me 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 prepro 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 head 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 i 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 co 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} l @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 turnin 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. Index: gcc/doc/cppwarnopts.texi =================================================================== --- gcc/doc/cppwarnopts.texi (revision 244009) +++ gcc/doc/cppwarnopts.texi (working copy) @@ -46,14 +46,14 @@ This warning is also enabled by @option{ @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 @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.