From 51db43377b412ff5325c4ae549f1da6b6975c6e1 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky <mjo@gentoo.org> Date: Thu, 2 Jul 2020 15:48:52 -0400 Subject: [PATCH] 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. Signed-off-by: Michael Orlitzky <mjo@gentoo.org> --- ebuild-writing/variables/text.xml | 146 ++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index 058f466..9342ba6 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -806,5 +806,151 @@ 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. +</p> +<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><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>x86_64-pc-linux-gnu-ar</ti> + </tr> + <tr> + <ti><c>ARFLAGS</c></ti> + <ti>flags for <c>$AR</c></ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>-v</ti> + </tr> + <tr> + <ti><c>AS</c></ti> + <ti><uri link="http://www.tom-yam.or.jp/2238/ref/as.pdf">as</uri>-compatible assembler</ti> + <ti><uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">GNU make</uri></ti> + <ti>x86_64-pc-linux-gnu-as</ti> + </tr> + <tr> + <ti><c>ASFLAGS</c></ti> + <ti>flags for <c>$AS</c></ti> + <ti><uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">GNU make</uri></ti> + <ti>--reduce-memory-overheads</ti> + </tr> + <tr> + <ti><c>CC</c></ti> + <ti>C compiler driver (also usually used for linking)</ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>clang-9</ti> + </tr> + <tr> + <ti><c>CFLAGS</c></ti> + <ti>flags for <c>$CC</c></ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>-march=native</ti> + </tr> + <tr> + <ti><c>CPPFLAGS</c></ti> + <ti>flags for the C preprocessor</ti> + <ti><uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">GNU make</uri></ti> + <ti>-D_GNU_SOURCE</ti> + </tr> + <tr> + <ti><c>CXX</c></ti> + <ti>C++ compiler driver (also usually used for linking)</ti> + <ti><uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">GNU make</uri></ti> + <ti>clang++</ti> + </tr> + <tr> + <ti><c>CXXFLAGS</c></ti> + <ti>flags for <c>$CXX</c></ti> + <ti><uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">GNU make</uri></ti> + <ti>-fvisibility=hidden</ti> + </tr> + <tr> + <ti><c>FC</c></ti> + <ti>FORTRAN compiler driver (also usually used for linking)</ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>x86_64-pc-linux-gnu-gfortran-9.3.0</ti> + </tr> + <tr> + <ti><c>FFLAGS</c></ti> + <ti>flags for <c>$FC</c></ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>-march=native</ti> + </tr> + <tr> + <ti><c>LD</c></ti> + <ti>dynamic linker</ti> + <ti><uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT">GNU libtool</uri></ti> + <ti>x86_64-pc-linux-gnu-ld</ti> + </tr> + <tr> + <ti><c>LDFLAGS</c></ti> + <ti>flags for the <e>compiler driver</e> to pass to its linker</ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>-Wl,-O1 -Wl,--as-needed</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><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>/usr/bin/flex</ti> + </tr> + <tr> + <ti><c>LFLAGS</c></ti> + <ti>flags for <c>$LEX</c></ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>--8bit --posix-compat</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><uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT">GNU libtool</uri></ti> + <ti>x86_64-pc-linux-gnu-nm</ti> + </tr> + <tr> + <ti><c>RANLIB</c></ti> + <ti>archive index generator</ti> + <ti><uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT">GNU libtool</uri></ti> + <ti>x86_64-pc-linux-gnu-ranlib</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><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>/usr/bin/bison</ti> + </tr> + <tr> + <ti><c>YFLAGS</c></ti> + <ti>flags for <c>$YACC</c></ti> + <ti><uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">POSIX make</uri></ti> + <ti>-d</ti> + </tr> +</table> +</body> +</section> + </chapter> </guide> -- 2.26.2