From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 27A7113835B for ; Sun, 21 Mar 2021 06:06:23 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1886BE0830; Sun, 21 Mar 2021 06:06:22 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id DC0E7E0849 for ; Sun, 21 Mar 2021 06:06:21 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 66370335D1A for ; Sun, 21 Mar 2021 06:06:20 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id BE20E5C5 for ; Sun, 21 Mar 2021 06:06:18 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1616306773.557f3dbd124b34928e4e11d8e51d8822e281f240.ulm@gentoo> Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/ X-VCS-Repository: proj/devmanual X-VCS-Files: ebuild-writing/common-mistakes/text.xml X-VCS-Directories: ebuild-writing/common-mistakes/ X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 557f3dbd124b34928e4e11d8e51d8822e281f240 X-VCS-Branch: master Date: Sun, 21 Mar 2021 06:06:18 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: 4f54fefc-1872-415a-b776-ddf20d1fbd44 X-Archives-Hash: d369f7539b93dcea225aea032e9ac649 commit: 557f3dbd124b34928e4e11d8e51d8822e281f240 Author: Ulrich Müller gentoo org> AuthorDate: Sun Mar 21 06:02:20 2021 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Sun Mar 21 06:06:13 2021 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=557f3dbd ebuild-writing/common-mistakes: Reformat paragraphs in the -Werror section No change of wording. Signed-off-by: Ulrich Müller gentoo.org> ebuild-writing/common-mistakes/text.xml | 44 ++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 0d3d441..dcdc969 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -19,7 +19,8 @@ writing ebuilds.

The static use-flag should only be used to make a binary use static linking instead of dynamic linking. It should not be used to make a library -install static libraries. Instead, the static-libs use-flag is used for this. +install static libraries. Instead, the static-libs use-flag is used for +this.

@@ -104,32 +105,41 @@ preferred. -Werror compiler flag not removed

-"-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +"-Werror" is a flag which turns all warnings into errors and thus will abort +compiling if any warning is encountered.

Rationale

-This flag is not recommended for releases and should always be disabled when encountered in build-logs, because there are numerous cases where this breaks without purpose, e.g.: +This flag is not recommended for releases and should always be disabled when +encountered in build-logs, because there are numerous cases where this breaks +without purpose, e.g.:

  • - new warnings on version bumps of GCC/GLIBC the developer was not aware of at the point of coding + new warnings on version bumps of GCC/GLIBC the developer was not aware of + at the point of coding
  • some autoconf checks will fail badly
  • - libraries adding deprecated API warnings although that API is still working/supported + libraries adding deprecated API warnings although that API is still + working/supported
  • - on less known architectures we may get different/more warnings than on common ones + on less known architectures we may get different/more warnings than on + common ones
  • - random breakage depending on what distro/architecture/library version/kernel/userland the developer was testing "-Werror" on + random breakage depending on what distro/architecture/library + version/kernel/userland the developer was testing "-Werror" on

-Turning off "-Werror" we will still see the warnings, but there is no reason that they cause compile failure. Also note that Portage already emits QA notices about gcc warnings that can cause runtime breakage. +Turning off "-Werror" we will still see the warnings, but there is no reason +that they cause compile failure. Also note that Portage already emits QA +notices about gcc warnings that can cause runtime breakage.

How to fix

@@ -138,10 +148,16 @@ To fix the affected build system you should try the following methods:

  • - remove the compiler flag from the build system, e.g. Makefile.am or configure.ac or even provide a switch (for autotools based build systems that could be "--disable-werror", which is good for sending a patch upstream) + remove the compiler flag from the build system, e.g. Makefile.am or + configure.ac or even provide a switch (for autotools based build + systems that could be "--disable-werror", which is good for sending a patch + upstream)
  • - use append-flags -Wno-error (needs flag-o-matic.eclass); for this to work the environment flags have to be respected and placed after build system flags; this method is not preferred as it will disable all "-Werror=specific-warning" flags as well, see next section + use append-flags -Wno-error (needs flag-o-matic.eclass); for this + to work the environment flags have to be respected and placed after build + system flags; this method is not preferred as it will disable all + "-Werror=specific-warning" flags as well, see next section

@@ -150,7 +166,13 @@ Always check that it's really gone in the build log.

Specific -Werror=... flags

-GCC can turn any specific warning into an error. A specific -Werror flag would be "-Werror=implicit-function-declaration" for example and will only affect warnings about implicit function declarations. It's mostly safe to leave these untouched, cause they are pinned to this issue and should not cause random build time breakage. Also, we can expect that upstream did this on purpose to avoid known runtime errors and not just for testing their builds. However you should check the specified warnings yourself or ask other developers if unsure. +GCC can turn any specific warning into an error. A specific -Werror flag would +be "-Werror=implicit-function-declaration" for example and will only affect +warnings about implicit function declarations. It's mostly safe to leave these +untouched, cause they are pinned to this issue and should not cause random +build time breakage. Also, we can expect that upstream did this on purpose to +avoid known runtime errors and not just for testing their builds. However you +should check the specified warnings yourself or ask other developers if unsure.

Exceptions