From patchwork Thu Jun 1 03:31:36 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jason Merrill X-Patchwork-Id: 1788760 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha256 header.s=default header.b=KywKrxk8; dkim-atps=neutral Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4QWsBh1yCrz20QB for ; Thu, 1 Jun 2023 13:32:12 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6900E3858031 for ; Thu, 1 Jun 2023 03:32:09 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6900E3858031 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1685590329; bh=TqCr69eSSd2Ks8+S9SVbhg6wyj6ycMVOHoAzp8Il6IY=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=KywKrxk8C5jMGHAI+hQm9cueKZAhcGgy5aPNnP73bhV4G8ub17iDAvwjZNr5xgh5m 0ReAHG0QMB0bMqNT60Uf/Uthqi6obVUEXpld9YSGpgMqMjHbyiwn66HgFmQMCDrjGs Zv0YUiHZUp4JA+Otf+LAqwxHmbAMG6BbWnmUtsp8= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id CC07E3858D20 for ; Thu, 1 Jun 2023 03:31:48 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org CC07E3858D20 Received: from mail-qv1-f71.google.com (mail-qv1-f71.google.com [209.85.219.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-374-uA1O4lpcP2ux2MCB_QVExQ-1; Wed, 31 May 2023 23:31:42 -0400 X-MC-Unique: uA1O4lpcP2ux2MCB_QVExQ-1 Received: by mail-qv1-f71.google.com with SMTP id 6a1803df08f44-5eee6742285so6926446d6.2 for ; Wed, 31 May 2023 20:31:42 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1685590300; x=1688182300; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=TqCr69eSSd2Ks8+S9SVbhg6wyj6ycMVOHoAzp8Il6IY=; b=i+FuLZRkYtZHA0JyDJ6fV+vcF8MiJBHY452yGt3/DlH9KzD+hBmtS8Uv5ong5IDROv dLnmJO6E1pI52qIgsjrfwALegpEfuwpxXPE39qABXSnpQ3+/PsXocnmGCLe2Sfh2GbR5 8IPfWhQoxSpCTMQPbOcNF7meXMFIOC0tbhOBBwilWUuhD+SLGhlAp2EBx06Z0FJNqgk0 aiXPtmDBrAfijtuDRyy+RA8o5YzUkLSjI72MSGA8/mhGdFD9ZN7tCvrRl3dQwPcLVLFe Exy2fJrELxxWzsHMJgkvJ6Z0MLlS8OAGkDxxlAcLFo0bqbhGc2Cf2Xjs6P6cXyN6PzIz o7IQ== X-Gm-Message-State: AC+VfDzD4PZExBPe2g2M2SFd2kEkypGhRLpIm8PQqAQHvnaryezESxSD wIph7lgT9gtxms45AisYeCeyYtG9gdKypoIPM1qyGNh+ZVYpwc1LK8IrwXPHSmKUnG3/X+uBmf5 Hitr/IKc44rxRGWEa0Klnz0sEqw119d48kHDQGUmFxzgx3CUhckI1L1M6mFRzWhY2NVyS/19qaQ == X-Received: by 2002:ad4:4ead:0:b0:623:6fc8:f461 with SMTP id ed13-20020ad44ead000000b006236fc8f461mr8804845qvb.33.1685590299879; Wed, 31 May 2023 20:31:39 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ6X5On2CNEbeMBtxWRD8PH1GmSgOSkZaQECuZpBajLrB4ruUlw26nBj7didDr4p70k7/SzAFw== X-Received: by 2002:ad4:4ead:0:b0:623:6fc8:f461 with SMTP id ed13-20020ad44ead000000b006236fc8f461mr8804817qvb.33.1685590299276; Wed, 31 May 2023 20:31:39 -0700 (PDT) Received: from jason.com (130-44-146-16.s12558.c3-0.arl-cbr1.sbo-arl.ma.cable.rcncustomer.com. [130.44.146.16]) by smtp.gmail.com with ESMTPSA id w2-20020a0cef82000000b005e750d07153sm4887337qvr.135.2023.05.31.20.31.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 31 May 2023 20:31:38 -0700 (PDT) To: gcc-patches@gcc.gnu.org Subject: [PATCH] doc: improve docs for -pedantic{,-errors} Date: Wed, 31 May 2023 23:31:36 -0400 Message-Id: <20230601033136.1275711-1-jason@redhat.com> X-Mailer: git-send-email 2.31.1 MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jason Merrill via Gcc-patches From: Jason Merrill Reply-To: Jason Merrill Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" Tested by looking at the makeinfo output. OK for trunk? -- 8< -- Recent discussion of -Wimplicit led me to want to clarify this section of the documentation, and mark which diagnostics other than -Wpedantic are affected by -pedantic-errors. gcc/ChangeLog: * doc/invoke.texi (-Wpedantic): Improve clarity. --- gcc/doc/invoke.texi | 98 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 80 insertions(+), 18 deletions(-) base-commit: 0a479c31b515ee872f48d5b53254a01da0fba61f diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 898a88ce33e..54edf8753a2 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -3701,6 +3701,9 @@ in C++20 with a pedantic warning that can be disabled with Enabled by default with @option{-std=c++20} unless @option{-Wno-deprecated}, and with @option{-std=c++23} regardless of @option{-Wno-deprecated}. +This warning is upgraded to an error by @option{-pedantic-errors} in +C++23 mode or later. + @opindex Wctad-maybe-unsupported @opindex Wno-ctad-maybe-unsupported @item -Wctad-maybe-unsupported @r{(C++ and Objective-C++ only)} @@ -5987,15 +5990,16 @@ warnings, in some cases it may also cause false positives. @item -Wpedantic @itemx -pedantic Issue all the warnings demanded by strict ISO C and ISO C++; -reject all programs that use forbidden extensions, and some other -programs that do not follow ISO C and ISO C++. For ISO C, follows the -version of the ISO C standard specified by any @option{-std} option used. +diagnose all programs that use forbidden extensions, and some other +programs that do not follow ISO C and ISO C++. This follows the version +of the ISO C or C++ standard specified by any @option{-std} option used. Valid ISO C and ISO C++ programs should compile properly with or without this option (though a rare few require @option{-ansi} or a -@option{-std} option specifying the required version of ISO C)@. However, +@option{-std} option specifying the version of the standard)@. However, without this option, certain GNU extensions and traditional C and C++ -features are supported as well. With this option, they are rejected. +features are supported as well. With this option, they are diagnosed +(or rejected with @option{-pedantic-errors}). @option{-Wpedantic} does not cause warning messages for use of the alternate keywords whose names begin and end with @samp{__}. This alternate @@ -6006,16 +6010,10 @@ Pedantic warnings are also disabled in the expression that follows these escape routes; application programs should avoid them. @xref{Alternate Keywords}. -Some users try to use @option{-Wpedantic} to check programs for strict ISO -C conformance. They soon find that it does not do quite what they want: -it finds some non-ISO practices, but not all---only those for which -ISO C @emph{requires} a diagnostic, and some others for which -diagnostics have been added. - -A feature to report any failure to conform to ISO C might be useful in -some instances, but would require considerable additional work and would -be quite different from @option{-Wpedantic}. We don't have plans to -support such a feature in the near future. +Some warnings about non-conforming programs are controlled by options +other than @option{-Wpedantic}; in many cases they are implied by +@option{-Wpedantic} but can be disabled separately by their specific +option, e.g. @option{-Wpedantic -Wno-pointer-sign}. Where the standard specified with @option{-std} represents a GNU extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a @@ -6033,8 +6031,44 @@ Give an error whenever the @dfn{base standard} (see @option{-Wpedantic}) requires a diagnostic, in some cases where there is undefined behavior at compile-time and in some other cases that do not prevent compilation of programs that are valid according to the standard. This is not -equivalent to @option{-Werror=pedantic}, since there are errors enabled -by this option and not enabled by the latter and vice versa. +equivalent to @option{-Werror=pedantic}: the latter option is unlikely to be +useful, as it only makes errors of the diagnostics that are controlled by +@option{-Wpedantic}, whereas this option also affects required diagnostics that +are always enabled or controlled by options other than @option{-Wpedantic}. + +If you want the required diagnostics that are warnings by default to +be errors instead, but don't also want to enable the @option{-Wpedantic} +diagnostics, you can specify @option{-pedantic-errors -Wno-pedantic} +(or @option{-pedantic-errors -Wno-error=pedantic} to enable them but +only as warnings). + +Some required diagnostics are errors by default, but can be reduced to +warnings using @option{-fpermissive} or their specific warning option, +e.g. @option{-Wno-error=narrowing}. + +Some diagnostics for non-ISO practices are controlled by specific +warning options other than @option{-Wpedantic}, but are also made +errors by @option{-pedantic-errors}. For instance: + +@gccoptlist{ +-Wattributes @r{(for standard attributes)} +-Wchanges-meaning @r{(C++)} +-Wcomma-subscript @r{(C++23 or later)} +-Wdeclaration-after-statement @r{(C90 or earlier)} +-Wimplicit-int @r{(C99 or later)} +-Wimplicit-function-declaration @r{(C99 or later)} +-Wincompatible-pointer-types +-Wint-conversion +-Wlong-long @r{(C90 or earlier)} +-Wmain +-Wnarrowing @r{(C++11 or later)} +-Wpointer-arith +-Wpointer-sign +-Wincompatible-pointer-types +-Wregister @r{(C++17 or later)} +-Wvla @r{(C90 or earlier)} +-Wwrite-strings @r{(C++11 or later)} +} @opindex Wall @opindex Wno-all @@ -6683,13 +6717,16 @@ This option controls warnings when a declaration does not specify a type. This warning is enabled by default in C99 and later dialects of C, and also by @option{-Wall}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wimplicit-function-declaration @opindex Wno-implicit-function-declaration @item -Wno-implicit-function-declaration @r{(C and Objective-C only)} This option controls warnings when a function is used before being declared. This warning is enabled by default in C99 and later dialects of C, and also by @option{-Wall}. -The warning is made into an error by @option{-pedantic-errors}. + +This warning is upgraded to an error by @option{-pedantic-errors}. @opindex Wimplicit @opindex Wno-implicit @@ -6879,6 +6916,8 @@ arguments, two, or three arguments of appropriate types. This warning is enabled by default in C++ and is enabled by either @option{-Wall} or @option{-Wpedantic}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wmisleading-indentation @opindex Wno-misleading-indentation @item -Wmisleading-indentation @r{(C and C++ only)} @@ -8340,6 +8379,8 @@ types. This warning is for cases not covered by @option{-Wno-pointer-sign}, which warns for pointer argument passing or assignment with different signedness. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wno-int-conversion @opindex Wint-conversion @item -Wno-int-conversion @r{(C and Objective-C only)} @@ -8348,6 +8389,8 @@ conversions. This warning is about implicit conversions; for explicit conversions the warnings @option{-Wno-int-to-pointer-cast} and @option{-Wno-pointer-to-int-cast} may be used. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wzero-length-bounds @opindex Wzero-length-bounds @item -Wzero-length-bounds @@ -8548,6 +8591,8 @@ 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 Labels and Declarations}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wshadow @opindex Wno-shadow @item -Wshadow @@ -8739,6 +8784,8 @@ convenience in calculations with @code{void *} pointers and pointers to functions. In C++, warn also when an arithmetic operation involves @code{NULL}. This warning is also enabled by @option{-Wpedantic}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wpointer-compare @opindex Wno-pointer-compare @item -Wno-pointer-compare @@ -8825,6 +8872,9 @@ floating-point types, and so on. This option is independent of the standards mode. Warnings are disabled in the expression that follows @code{__extension__}. +When not compiling in C2X mode, these warnings are upgraded to errors +by @option{-pedantic-errors}. + @opindex Wc++-compat @opindex Wno-c++-compat @item -Wc++-compat @r{(C and Objective-C only)} @@ -8958,6 +9008,9 @@ When compiling C++, warn about the deprecated conversion from string literals to @code{char *}. This warning is enabled by default for C++ programs. +This warning is upgraded to an error by @option{-pedantic-errors} in +C++11 mode or later. + @opindex Wclobbered @opindex Wno-clobbered @item -Wclobbered @@ -9390,6 +9443,9 @@ unrecognized attributes, function attributes applied to variables, etc. This does not stop errors for incorrect use of supported attributes. +Warnings about ill-formed uses of standard attributes are upgraded to +errors by @option{-pedantic-errors}. + Additionally, using @option{-Wno-attributes=}, it is possible to suppress warnings about unknown scoped attributes (in C++11 and C2X). For example, @option{-Wno-attributes=vendor::attr} disables warning about the following @@ -9929,6 +9985,8 @@ Warn if @code{long long} type is used. This is enabled by either @option{-Wpedantic} or @option{-Wtraditional} in ISO C90 and C++98 modes. To inhibit the warning messages, use @option{-Wno-long-long}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wvariadic-macros @opindex Wno-variadic-macros @item -Wvariadic-macros @@ -9962,6 +10020,8 @@ Warn if a variable-length array is used in the code. @option{-Wno-vla} prevents the @option{-Wpedantic} warning of the variable-length array. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wvla-larger-than= @opindex Wno-vla-larger-than @item -Wvla-larger-than=@var{byte-size} @@ -10066,6 +10126,8 @@ This option is only supported for C and Objective-C@. It is implied by @option{-Wall} and by @option{-Wpedantic}, which can be disabled with @option{-Wno-pointer-sign}. +This warning is upgraded to an error by @option{-pedantic-errors}. + @opindex Wstack-protector @opindex Wno-stack-protector @item -Wstack-protector