public inbox for gentoo-commits@lists.gentoo.org
 help / color / mirror / Atom feed
From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/
Date: Sun, 21 Mar 2021 06:06:18 +0000 (UTC)	[thread overview]
Message-ID: <1616306773.557f3dbd124b34928e4e11d8e51d8822e281f240.ulm@gentoo> (raw)

commit:     557f3dbd124b34928e4e11d8e51d8822e281f240
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 06:02:20 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> 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 <ulm <AT> 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.
 <p>
 The <c>static</c> 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 <c>static-libs</c> use-flag is used for this.
+install static libraries. Instead, the <c>static-libs</c> use-flag is used for
+this.
 </p>
 </body>
 </subsection>
@@ -104,32 +105,41 @@ preferred.</note>
 <title>-Werror compiler flag not removed</title>
 <body>
 <p>
-"-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.
 </p>
 
 <p><b>Rationale</b></p>
 <p>
-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.:
 </p>
 <ul>
   <li>
-    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
   </li>
   <li>
     some autoconf checks will fail badly
   </li>
   <li>
-    libraries adding deprecated API warnings although that API is still working/supported
+    libraries adding deprecated API warnings although that API is still
+    working/supported
   </li>
   <li>
-    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
   </li>
   <li>
-    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
   </li>
 </ul>
 <p>
-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.
 </p>
 
 <p><b>How to fix</b></p>
@@ -138,10 +148,16 @@ To fix the affected build system you should try the following methods:
 </p>
 <ul>
   <li>
-    remove the compiler flag from the build system, <e>e.g. Makefile.am or configure.ac</e> 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>e.g. Makefile.am or
+    configure.ac</e> or even provide a switch (for autotools based build
+    systems that could be "--disable-werror", which is good for sending a patch
+    upstream)
   </li>
   <li>
-    use <e>append-flags -Wno-error</e> (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 <e>append-flags -Wno-error</e> (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
   </li>
 </ul>
 <p>
@@ -150,7 +166,13 @@ Always check that it's really gone in the build log.
 
 <p><b>Specific -Werror=... flags</b></p>
 <p>
-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.
 </p>
 
 <p><b>Exceptions</b></p>


             reply	other threads:[~2021-03-21  6:06 UTC|newest]

Thread overview: 46+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-21  6:06 Ulrich Müller [this message]
  -- strict thread matches above, loose matches on Subject: below --
2024-07-24 14:15 [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/common-mistakes/ Ulrich Müller
2022-01-22 23:43 Sam James
2021-12-22 15:38 Ulrich Müller
2021-09-17  9:09 Ulrich Müller
2021-08-14 10:00 Ulrich Müller
2021-08-01  2:43 Sam James
2021-08-01  2:38 Sam James
2021-08-01  2:38 Sam James
2021-08-01  2:38 Sam James
2021-08-01  2:38 Sam James
2021-08-01  2:38 Sam James
2021-03-30 18:20 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 18:15 Ulrich Müller
2021-03-30 16:10 Ulrich Müller
2021-03-30 16:10 Ulrich Müller
2021-03-29 20:44 Ulrich Müller
2021-02-06 10:35 Ulrich Müller
2017-01-25  5:31 Göktürk Yüksek
2017-01-25  5:31 Göktürk Yüksek
2017-01-21 19:21 Göktürk Yüksek
2016-10-28 17:13 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2014-10-18 17:36 Markos Chandras
2014-05-13 19:32 Ulrich Müller
2013-09-28 12:19 Markos Chandras
2012-12-30 14:21 Julian Ospald
2012-12-04 19:26 Julian Ospald
2012-11-23 18:02 Julian Ospald
2012-11-17 19:00 Markos Chandras
2012-11-11 19:33 Markos Chandras
2012-11-07 13:27 Michael Palimaka
2012-11-07 13:25 Michael Palimaka
2012-08-08 19:20 Markos Chandras
2011-03-09 16:42 Jeremy Olexa

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1616306773.557f3dbd124b34928e4e11d8e51d8822e281f240.ulm@gentoo \
    --to=ulm@gentoo.org \
    --cc=gentoo-commits@lists.gentoo.org \
    --cc=gentoo-dev@lists.gentoo.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox