From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-1264479-garchives=archives.gentoo.org@lists.gentoo.org>
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 2FD831382C5
	for <garchives@archives.gentoo.org>; Fri, 26 Mar 2021 19:05:48 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
	by pigeon.gentoo.org (Postfix) with SMTP id 7E0AAE0829;
	Fri, 26 Mar 2021 19:05:47 +0000 (UTC)
Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4])
	(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 55A10E0829
	for <gentoo-commits@lists.gentoo.org>; Fri, 26 Mar 2021 19:05:47 +0000 (UTC)
Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84])
	(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 EDD00335C30
	for <gentoo-commits@lists.gentoo.org>; Fri, 26 Mar 2021 19:05:45 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
	by oystercatcher.gentoo.org (Postfix) with ESMTP id 2EE884EE
	for <gentoo-commits@lists.gentoo.org>; Fri, 26 Mar 2021 19:05:44 +0000 (UTC)
From: "Ulrich Müller" <ulm@gentoo.org>
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" <ulm@gentoo.org>
Message-ID: <1616785536.d9793d70892f5107f4a140e14dfec15997ef65cc.ulm@gentoo>
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/
X-VCS-Repository: proj/devmanual
X-VCS-Files: ebuild-writing/variables/text.xml
X-VCS-Directories: ebuild-writing/variables/
X-VCS-Committer: ulm
X-VCS-Committer-Name: Ulrich Müller
X-VCS-Revision: d9793d70892f5107f4a140e14dfec15997ef65cc
X-VCS-Branch: master
Date: Fri, 26 Mar 2021 19:05:44 +0000 (UTC)
Precedence: bulk
List-Post: <mailto:gentoo-commits@lists.gentoo.org>
List-Help: <mailto:gentoo-commits+help@lists.gentoo.org>
List-Unsubscribe: <mailto:gentoo-commits+unsubscribe@lists.gentoo.org>
List-Subscribe: <mailto:gentoo-commits+subscribe@lists.gentoo.org>
List-Id: Gentoo Linux mail <gentoo-commits.gentoo.org>
X-BeenThere: gentoo-commits@lists.gentoo.org
X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply
X-Archives-Salt: 7726ce75-8302-4bb7-b70e-5a99a86c54d0
X-Archives-Hash: dfb7560b89319b76de4d10c818bac3e4

commit:     d9793d70892f5107f4a140e14dfec15997ef65cc
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jul  2 19:48:52 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 26 19:05:36 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d9793d70

ebuild-writing/variables: add a "User environment" section.

Gentoo has always tried to respect a user's CFLAGS environment
variable, ensuring that it is passed to the underlying build
system. Likewise, CC and LDFLAGS are well-respected these days.

Recently, we have added some other variables to this list, like NM,
RANLIB, LD, and AS. The meanings of most of these are enshrined in
toolchain-funcs.eclass, but in order to properly support them, we must
document their intended use so that user's can set them to the correct
value and developers can inject them into the right spot in the
upstream build system. One motivating example package is PARI, whose
build system interprets the LD environment variable in a different way
than GNU librool interprets it. If a user sets LD to something
appropriate for libtool, the PARI build will fail, and conversely;
that is, without help from the ebuild.

This commit adds a new section to the ebuild-writing/variables page
documenting the origin and intended use of these variables within
Gentoo. This should ensure that users and Gentoo developers agree on
their meanings, and will guide ebuild development when a problematic
upstream build system is encountered.

Closes: https://bugs.gentoo.org/730610
Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>
[Remove URI for "as". Whitespace fixes.]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 163 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 2ba4c4b..e947b88 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -806,5 +806,168 @@ REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"
 </subsection>
 </section>
 
+<section>
+<title>User environment</title>
+<body>
+
+<p>
+The following variables may be set in the user's environment and should be
+respected by all ebuilds. The purpose of each variable within Gentoo is listed
+alongside an example of a valid value. Upstream usage may diverge, but ebuilds
+should ensure that these variables are interpreted consistently within Gentoo.
+The chosen meanings are inspired by a few real and de-facto standards:
+</p>
+
+<ul>
+  <li>
+    <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">
+    The POSIX (2018) make specification</uri>
+  </li>
+  <li>
+    <uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">
+    The GNU make (v4.3) implementation</uri>
+  </li>
+  <li>
+    <uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT">
+    The GNU libtool (v2.4.6) package</uri>
+  </li>
+</ul>
+
+<p>
+Many of these variables only have an effect if they are invoked directly.
+For example, your compiler driver is usually responsible for assembling object
+files rather than a direct call to <c>${AS}</c>. In that case, setting
+<c>ASFLAGS</c> will have no effect on the build process; instead, you would set
+something like <c>CFLAGS="-Wa,-alh,-L"</c> to tell the C compiler to pass those
+flags to the assembler. The <c>LDFLAGS</c> variable is the exception to this
+rule, as it is intended to be passed to the compiler driver rather than
+<c>${LD}</c>.
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+    <th>Origin</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <ti><c>AR</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/ar.html">
+      ar</uri>-compatible library archiver
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>x86_64-pc-linux-gnu-ar</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ARFLAGS</c></ti>
+    <ti>flags for <c>${AR}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-v</c></ti>
+  </tr>
+  <tr>
+    <ti><c>AS</c></ti>
+    <ti>as-compatible assembler</ti>
+    <ti>GNU make</ti>
+    <ti><c>x86_64-pc-linux-gnu-as</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ASFLAGS</c></ti>
+    <ti>flags for <c>${AS}</c></ti>
+    <ti>GNU make</ti>
+    <ti><c>--reduce-memory-overheads</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CC</c></ti>
+    <ti>C compiler driver (also usually used for linking)</ti>
+    <ti>POSIX make</ti>
+    <ti><c>clang-9</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CFLAGS</c></ti>
+    <ti>flags for <c>${CC}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-march=native</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CPPFLAGS</c></ti>
+    <ti>flags for the C preprocessor</ti>
+    <ti>GNU make</ti>
+    <ti><c>-D_GNU_SOURCE</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CXX</c></ti>
+    <ti>C++ compiler driver (also usually used for linking)</ti>
+    <ti>GNU make</ti>
+    <ti><c>clang++</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CXXFLAGS</c></ti>
+    <ti>flags for <c>${CXX}</c></ti>
+    <ti>GNU make</ti>
+    <ti><c>-fvisibility=hidden</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LD</c></ti>
+    <ti>dynamic linker</ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-ld</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LDFLAGS</c></ti>
+    <ti>flags for the <e>compiler driver</e> to pass to its linker</ti>
+    <ti>POSIX make</ti>
+    <ti><c>-Wl,-O1 -Wl,--as-needed</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LEX</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/lex.html">
+      lex</uri>-compatible lexer
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>/usr/bin/flex</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LFLAGS</c></ti>
+    <ti>flags for <c>${LEX}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>--8bit --posix-compat</c></ti>
+  </tr>
+  <tr>
+    <ti><c>NM</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nm.html">
+      nm</uri>-compatible symbol extractor
+    </ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-nm</c></ti>
+  </tr>
+  <tr>
+    <ti><c>RANLIB</c></ti>
+    <ti>archive index generator</ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-ranlib</c></ti>
+  </tr>
+  <tr>
+    <ti><c>YACC</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html">
+      yacc</uri>-compatible compiler-compiler
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>/usr/bin/bison</c></ti>
+  </tr>
+  <tr>
+    <ti><c>YFLAGS</c></ti>
+    <ti>flags for <c>${YACC}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-d</c></ti>
+  </tr>
+</table>
+
+</body>
+</section>
 </chapter>
 </guide>