From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/
Date: Fri, 26 Mar 2021 19:05:44 +0000 (UTC) [thread overview]
Message-ID: <1616785536.d9793d70892f5107f4a140e14dfec15997ef65cc.ulm@gentoo> (raw)
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>
next reply other threads:[~2021-03-26 19:05 UTC|newest]
Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-26 19:05 Ulrich Müller [this message]
-- strict thread matches above, loose matches on Subject: below --
2022-08-25 16:42 [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/ Ulrich Müller
2022-08-25 16:42 Ulrich Müller
2022-08-25 16:42 Ulrich Müller
2022-02-18 18:19 Sam James
2022-02-16 18:43 Ulrich Müller
2022-02-16 18:02 Matthew Smith
2021-05-28 13:09 Ulrich Müller
2021-03-30 7:21 Ulrich Müller
2021-03-30 7:21 Ulrich Müller
2021-03-30 7:21 Ulrich Müller
2021-03-30 7:21 Ulrich Müller
2021-03-30 7:21 Ulrich Müller
2020-03-11 14:38 Ulrich Müller
2019-11-29 9:28 Ulrich Müller
2019-11-28 18:32 Göktürk Yüksek
2019-11-28 18:32 Göktürk Yüksek
2019-11-26 1:49 Göktürk Yüksek
2019-11-26 1:49 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-10-16 20:16 Göktürk Yüksek
2019-05-22 19:40 Göktürk Yüksek
2019-03-24 16:48 Ulrich Müller
2019-03-19 17:11 Brian Evans
2019-03-19 17:11 Brian Evans
2018-10-24 13:01 Brian Evans
2018-10-24 13:01 Brian Evans
2017-11-12 20:15 Ulrich Müller
2017-09-09 3:43 Göktürk Yüksek
2016-12-07 19:46 Göktürk Yüksek
2016-11-17 5:23 Göktürk Yüksek
2016-10-28 14:21 Göktürk Yüksek
2016-10-28 14:21 Göktürk Yüksek
2016-07-13 3:18 Göktürk Yüksek
2016-07-13 2:48 Göktürk Yüksek
2016-05-20 6:23 Göktürk Yüksek
2016-05-18 6:56 Göktürk Yüksek
2016-05-11 1:43 Mike Gilbert
2016-05-04 9:13 Göktürk Yüksek
2015-12-08 20:06 Ulrich Müller
2015-08-07 5:08 Mike Frysinger
2013-05-15 13:39 Dirkjan Ochtman
2013-05-15 13:39 Dirkjan Ochtman
2013-05-15 13:17 Dirkjan Ochtman
2012-11-24 19:12 Ulrich Mueller
2012-11-11 19:33 Markos Chandras
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=1616785536.d9793d70892f5107f4a140e14dfec15997ef65cc.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