[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     f5c32783df86fbdb63a4b333039764aa66fbb2fc
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Apr  2 07:01:27 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Apr 10 07:02:11 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f5c32783

general-concepts/use-flags: Change example to src_configure()

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 8953b87..54675f3 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -297,7 +297,7 @@ GnuTLS is more featureful than OpenSSL, it is favoured:
 </p>
 
 <codesample lang="ebuild">
-src_compile() {
+src_configure() {
 	local myconf
 
 	if use ssl &amp;&amp; use gnutls ; then
@@ -311,8 +311,6 @@ src_compile() {
 	econf \
 		# Other stuff
 		${myconf}
-
-	emake
 }
 </codesample>
 

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     29978d077d271058b31a4578617880013448093d
Author:     Jonas Frei <freijon <AT> pm <DOT> me>
AuthorDate: Tue Aug 22 03:17:10 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Aug 22 06:03:16 2023 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=29978d07

general-concepts/use-flags: Clarification about compiler flags

Signed-off-by: Jonas Frei <freijon <AT> pm.me>
[Whitespace fixed.]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 7d0047a..5caa430 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -82,10 +82,10 @@ instead, or controlled by a flag such as <c>minimal</c>.
 </p>
 
 <p>
-You should not introduce USE flags that merely manipulate <c>CFLAGS</c>,
-<c>FEATURES</c> or similar variables configured directly by the user. Instead,
-packages should avoid manipulating them at all, and let users set them directly.
-Common mistakes include:
+You should not introduce USE flags that manipulate compiler flags or similar
+variables configured directly by the user (e.g. <c>-O3</c>, <c>-flto</c>).
+Instead, packages should avoid manipulating them at all, and let users set
+them directly. Common mistakes include:
 </p>
 
 <ol>
@@ -114,7 +114,8 @@ There might be corner cases where these rules do not apply. For example, a few
 upstreams require users to use specific <c>CFLAGS</c> and reject bug reports
 against builds using other values. In this case, it is customary to strip flags
 by default and provide <c>custom-cflags</c> flag to allow users to force their
-preferred flags.
+preferred flags. Another exception are <c>CFLAGS</c> that enable/disable
+features at compile time (via pre-processor macros).
 </p>
 </body>
 </section>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Sam James]

commit:     3f0133a1c35420f3b67284e672538699a35c59fd
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Fri Jan 21 19:01:07 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Mon Feb 21 21:39:53 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3f0133a1

general-concepts/use-flags: give guidance on IUSE defaults

Avoid e.g. missing common functionality which upstream documentation
may refer to/assume.

Signed-off-by: Sam James <sam <AT> gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/265
Signed-off-by: Sam James <sam <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 02f1788..0605e91 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -203,6 +203,18 @@ Add <c>+</c> or <c>-</c> before the name of the use flag in <c>IUSE</c> to turn
 it on or off by default.
 </p>
 
+<p>
+IUSE defaults should be used sparingly. Reasons to exclude/default-disable a
+feature may include e.g. large build time for a dependency, or a
+configuration that the Gentoo maintainer is unable to test at runtime.
+</p>
+
+<p>
+The IUSE defaults for a package should not leave a package in a non-functional
+state or lacking important, common functionality. Consulting upstream
+documentation may be useful for assessing this.
+</p>
+
 <important>
 Adding <c>-</c> before a flag in <c>IUSE</c> is pretty much useless, as it will
 neither override the user configuration (<c>make.conf</c>) nor the profile

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Sam James]

commit:     ae56b20ca8ddb0b5b355c4127c5aeff17c3e8451
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Aug  1 02:09:23 2021 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sun Aug  1 02:09:23 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ae56b20c

general-concepts/use-flags: sort USE flags in example

Signed-off-by: Sam James <sam <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 1f731ae..02f1788 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -217,7 +217,7 @@ on USE-ordering in Portage.
 
 EAPI=7
 
-IUSE="foo +bar"
+IUSE="+bar foo"
 </codesample>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Sam James]

commit:     f59cf426916b5be25623688d8216667ec5f8d519
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Aug  1 02:08:05 2021 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sun Aug  1 02:08:05 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f59cf426

general-concepts/use-flags: fix minor 'varibles' typo

Signed-off-by: Sam James <sam <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 19f411d..1f731ae 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -97,8 +97,8 @@ Common mistakes include:
 	</li>
 
 	<li>
-	Introducing <c>lto</c> flag to force <c>-flto</c>. This is something user
-	should set directly in flag varibles.
+	Introducing <c>lto</c> flag to force <c>-flto</c>. This is something the user
+	should set directly in flag variables.
 	</li>
 
 	<li>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     d8e2ee736cad825f7214516ded3bfe03845bee95
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Apr  4 09:03:37 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Apr 10 07:02:12 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d8e2ee73

general-concepts/use-flags: Update example to current best practice

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index d5aae0c..19f411d 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -300,10 +300,8 @@ GnuTLS is more featureful than OpenSSL, it is favoured:
 src_configure() {
 	local myconf
 
-	if use ssl &amp;&amp; use gnutls ; then
-		myconf+=" --enable-ssl --with-ssl=gnutls"
-	elif use ssl &amp;&amp; ! use gnutls ; then
-		myconf+=" --enable-ssl --with-ssl=openssl"
+	if use ssl; then
+		myconf+=" --enable-ssl --with-ssl=$(usex gnutls gnutls openssl)"
 	else
 		myconf+=" --disable-ssl"
 	fi

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     6639f3afc0f1abfbb89cd7abd9d0dd74965bebe2
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Apr  2 07:16:12 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Apr 10 07:02:12 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6639f3af

general-concepts/use-flags: Use += operator in example

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 54675f3..d5aae0c 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -301,11 +301,11 @@ src_configure() {
 	local myconf
 
 	if use ssl &amp;&amp; use gnutls ; then
-		myconf="${myconf} --enable-ssl --with-ssl=gnutls"
+		myconf+=" --enable-ssl --with-ssl=gnutls"
 	elif use ssl &amp;&amp; ! use gnutls ; then
-		myconf="${myconf} --enable-ssl --with-ssl=openssl"
+		myconf+=" --enable-ssl --with-ssl=openssl"
 	else
-		myconf="${myconf} --disable-ssl"
+		myconf+=" --disable-ssl"
 	fi
 
 	econf \

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     ae1c2fcad41153e0b89c9bf3d4109d13e36234bd
Author:     Thomas Deutschmann <whissi <AT> gentoo <DOT> org>
AuthorDate: Fri Apr  2 00:10:12 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Apr  2 06:59:55 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ae1c2fca

general-concepts/use-flags: Fix indentation in code example

Closes: https://github.com/gentoo/devmanual/pull/215
Signed-off-by: Thomas Deutschmann <whissi <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index dd9b3fd..8953b87 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -305,7 +305,7 @@ src_compile() {
 	elif use ssl &amp;&amp; ! use gnutls ; then
 		myconf="${myconf} --enable-ssl --with-ssl=openssl"
 	else
-	myconf="${myconf} --disable-ssl"
+		myconf="${myconf} --disable-ssl"
 	fi
 
 	econf \

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     4386ee9536983a2a506791efcb90b12223f7f5bc
Author:     Stefan Strogin <steils <AT> gentoo <DOT> org>
AuthorDate: Fri May 24 07:32:55 2019 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri May 24 08:39:25 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4386ee95

general-concepts/use-flags: remove redundant 'die' from the example

Signed-off-by: Stefan Strogin <steils <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 04ebee2..74cb45d 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -283,7 +283,7 @@ src_compile() {
 		# Other stuff
 		${myconf}
 
-	emake || die "make failed"
+	emake
 }
 </codesample>
 

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Göktürk Yüksek]

commit:     ac170fabb913b0818eec678c4be6f1b7a05f8a34
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Apr 22 19:49:49 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:34:15 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ac170fab

general-concepts/use-flags: Explain resolving automagic deps

Explain how developers should resolve automagic deps properly (via
upstream patch), and how they can easily solve it locally (via cache
variables or forcing dep unconditionally).

Suggested-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 4d56d97..186c51d 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -27,6 +27,16 @@ dependency is not detected by the package manager tools and can easily
 break, among other issues.
 </p>
 
+<p>
+Automagic dependencies are preferably fixed by preparing a build system patch
+adding appropriate options to control the dependency in question, and submitting
+this patch upstream for the benefit of all users. To avoid carrying additional
+patches downstream, automagic dependencies can usually be worked around using
+special build system options (e.g. cache variables in autotools) or through
+depending on the relevant packages unconditionally (i.e. forcing the check
+to always succeed).
+</p>
+
 <note>
 The status of USE flags is saved in the VDB, and their value in
 <c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Göktürk Yüksek]

commit:     83e7f6d3a5430c17d234d5eb77685cdd7bc6df6d
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 13 21:40:22 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:34:07 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=83e7f6d3

general-concepts/use-flags: Split out use cases for not using flags

Split out the paragraph on not using USE flags for runtime dependencies
into a separate section.  Include the policy of not using USE flags
for small files.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 41 ++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index de61874..c20e8d0 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -27,6 +27,23 @@ dependency is not detected by the package manager tools and can easily
 break, among other issues.
 </p>
 
+<note>
+The status of USE flags is saved in the VDB, and their value in
+<c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that
+setting or unsetting a USE flag between merge and unmerge has no effect.
+</note>
+</body>
+
+<section>
+<title>When not to use USE flags?</title>
+<body>
+<p>
+While <c>USE</c> flags are generally considered beneficial to users, there
+are valid use cases for avoiding them. When writing ebuilds, consider whether
+to add flags for particular conditional features, or explore one
+of the alternative solutions described below.
+</p>
+
 <p>
 The usage of a <c>USE</c> flag should not control runtime dependencies when
 the package does not link to it. Doing so will create extra
@@ -35,12 +52,26 @@ change on disk. This should be avoided and instead can be conveyed to the
 user via post install messages if needed.
 </p>
 
-<note>
-The status of USE flags is saved in the VDB, and their value in
-<c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that
-setting or unsetting a USE flag between merge and unmerge has no effect.
-</note>
+<p>
+<c>USE</c> flags must not be used to control installing files that are small,
+non-intrusive, do not introduce additional build-time dependencies or cause
+a significant increase in build time. Examples of such files are bash completion
+files, init.d scripts, logrotate configuration files, systemd service files.
+The rationale is the same as above. Instead, those files must be installed
+unconditionally.
+</p>
+
+<p>
+A similar case can be made for packages having multiple conditional programs
+or modules. Whenever this results in a large number of <c>USE</c> flags that
+would force the user to spend a lot of time choosing compatible flags
+and possibly rebuilding after incomplete choices, consider reducing the use
+of flags to those programs or modules that have external dependencies
+and/or long build times. The rest of them should be built unconditionally
+instead, or controlled by a flag such as <c>minimal</c>.
+</p>
 </body>
+</section>
 
 <section>
 <title><c>noblah</c> USE Flags</title>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Göktürk Yüksek]

commit:     168d155d517e4ad08dacba6fd9d0769278bc4922
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Thu Apr 25 14:07:23 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:34:18 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=168d155d

general-concepts/use-flags: Grammar in VDB paragraph

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 186c51d..04ebee2 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -38,8 +38,8 @@ to always succeed).
 </p>
 
 <note>
-The status of USE flags is saved in the VDB, and their value in
-<c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that
+The states of USE flags are saved in the VDB, and their values in
+<c>pkg_prerm</c> and <c>pkg_postrm</c> are taken from there. This means that
 setting or unsetting a USE flag between merge and unmerge has no effect.
 </note>
 </body>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Göktürk Yüksek]

commit:     add4db87d50f4633dac12a21f5c0f98bc86cc5d6
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Apr 14 09:44:18 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:34:11 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=add4db87

general-concepts/use-flags: Also note about flags controlling CFLAGS

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index c20e8d0..4d56d97 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -70,6 +70,42 @@ of flags to those programs or modules that have external dependencies
 and/or long build times. The rest of them should be built unconditionally
 instead, or controlled by a flag such as <c>minimal</c>.
 </p>
+
+<p>
+You should not introduce USE flags that merely manipulate <c>CFLAGS</c>,
+<c>FEATURES</c> or similar variables configured directly by the user. Instead,
+packages should avoid manipulating them at all, and let users set them directly.
+Common mistakes include:
+</p>
+
+<ol>
+	<li>
+	Using <c>debug</c> USE flag to force <c>-O0 -g</c> and disable
+	stripping. The correct purpose of <c>debug</c> flag is to control additional
+	debug code paths. The use of correct flags and features to preserve
+	debugging information is user's responsibility.
+	</li>
+
+	<li>
+	Introducing <c>lto</c> flag to force <c>-flto</c>. This is something user
+	should set directly in flag varibles.
+	</li>
+
+	<li>
+	Using <c>CPU_FLAGS_*</c> to control <c>-m*</c> options. Those flags are
+	intended to control code paths explicitly requiring specific CPU extensions,
+	e.g. separate assembly. Compiler-generated assembly should respect user's
+	<c>-march</c> choice.
+	</li>
+</ol>
+
+<p>
+There might be corner cases where these rules do not apply. For example, a few
+upstreams require users to use specific <c>CFLAGS</c> and reject bug reports
+against builds using other values. In this case, it is customary to strip flags
+by default and provide <c>custom-cflags</c> flag to allow users to force their
+preferred flags.
+</p>
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Göktürk Yüksek]

commit:     a5f4ce3b3a39db8f6944ba9f1a1c7fb88f2f6990
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Apr 21 21:25:12 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:34:02 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a5f4ce3b

general-concepts/use-flags: Reindent to match devmanual style

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 general-concepts/use-flags/text.xml | 226 ++++++++++++++++++------------------
 1 file changed, 113 insertions(+), 113 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 0e46546..de61874 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -5,40 +5,40 @@
 
 <body>
 <p>
-	<c>USE</c> flags are to control optional dependencies and settings which
-	the user may reasonably want to select. For example, <c>app-editors/vim</c>
-	can optionally build with support for the <c>ruby</c> interpreter, and it
-	needs <c>dev-lang/ruby</c> installed to do this <d/> we use the ruby
-	<c>USE</c> flag to provide this option. On the other hand,
-	<c>app-text/glark</c> requires <c>ruby</c> no matter what, so no <c>USE</c>
-	flag is used there.
+<c>USE</c> flags are to control optional dependencies and settings which
+the user may reasonably want to select. For example, <c>app-editors/vim</c>
+can optionally build with support for the <c>ruby</c> interpreter, and it
+needs <c>dev-lang/ruby</c> installed to do this <d/> we use the ruby
+<c>USE</c> flag to provide this option. On the other hand,
+<c>app-text/glark</c> requires <c>ruby</c> no matter what, so no <c>USE</c>
+flag is used there.
 </p>
 
 <p>
-	No combination of <c>USE</c> flags should cause a package to fail to build
-	because users can set any combination of flags.
+No combination of <c>USE</c> flags should cause a package to fail to build
+because users can set any combination of flags.
 </p>
 
 <p>
-	Packages should not configure and link based upon what is available at
-	compile time <d/> any autodetection must be overridden. This is commonly
-	referred to as the dependency being "automagic" - This is bad because the
-	dependency is not detected by the package manager tools and can easily
-	break, among other issues.
+Packages should not configure and link based upon what is available at
+compile time <d/> any autodetection must be overridden. This is commonly
+referred to as the dependency being "automagic" - This is bad because the
+dependency is not detected by the package manager tools and can easily
+break, among other issues.
 </p>
 
 <p>
-	The usage of a <c>USE</c> flag should not control runtime dependencies when
-	the package does not link to it. Doing so will create extra
-	configuration for the package and re-compilation for no underlying file
-	change on disk. This should be avoided and instead can be conveyed to the
-	user via post install messages if needed.
+The usage of a <c>USE</c> flag should not control runtime dependencies when
+the package does not link to it. Doing so will create extra
+configuration for the package and re-compilation for no underlying file
+change on disk. This should be avoided and instead can be conveyed to the
+user via post install messages if needed.
 </p>
 
 <note>
-	The status of USE flags is saved in the VDB, and their value in
-	<c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that
-	setting or unsetting a USE flag between merge and unmerge has no effect.
+The status of USE flags is saved in the VDB, and their value in
+<c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that
+setting or unsetting a USE flag between merge and unmerge has no effect.
 </note>
 </body>
 
@@ -46,20 +46,20 @@
 <title><c>noblah</c> USE Flags</title>
 <body>
 <p>
-	Avoid <c>noblah</c> style <c>USE</c> flags. These break <c>use.mask</c> and
-	cause all sorts of complications for arch developers. Here's why:
+Avoid <c>noblah</c> style <c>USE</c> flags. These break <c>use.mask</c> and
+cause all sorts of complications for arch developers. Here's why:
 </p>
 
 <p>
-	Consider a hypothetical package named 'vplayer', which plays videos. This
-	package has optional support, via <c>USE</c> flags, for various sound and
-	video output methods, various video codecs and so on.
+Consider a hypothetical package named 'vplayer', which plays videos. This
+package has optional support, via <c>USE</c> flags, for various sound and
+video output methods, various video codecs and so on.
 </p>
 
 <p>
-	One of vplayer's optional features is support for the 'fakemedia' codec,
-	which is unfortunately only available as a dodgy x86 binary. We <e>could</e>
-	handle this by doing something like:
+One of vplayer's optional features is support for the 'fakemedia' codec,
+which is unfortunately only available as a dodgy x86 binary. We <e>could</e>
+handle this by doing something like:
 </p>
 
 <codesample lang="ebuild">
@@ -67,15 +67,15 @@ RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"
 </codesample>
 
 <p>
-	Except this is pretty nasty <d/> what happens when an AMD64 binary is made
-	as well? Also, users on other archs will see fakemedia listed in
-	<c>emerge -pv</c> output, even though it is not actually available.
+Except this is pretty nasty <d/> what happens when an AMD64 binary is made
+as well? Also, users on other archs will see fakemedia listed in
+<c>emerge -pv</c> output, even though it is not actually available.
 </p>
 
 <p>
-	Similarly, say vplayer supports output via the ALSA codec as one option.
-	However, ALSA isn't (or wasn't when this example was written) available on
-	SPARC or Alpha. So we could do:
+Similarly, say vplayer supports output via the ALSA codec as one option.
+However, ALSA isn't (or wasn't when this example was written) available on
+SPARC or Alpha. So we could do:
 </p>
 
 <codesample lang="ebuild">
@@ -83,18 +83,18 @@ DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )"
 </codesample>
 
 <p>
-	Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output.
-	Also, once ALSA starts working on SPARC, every ebuild that does this would
-	have to be manually edited.
+Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output.
+Also, once ALSA starts working on SPARC, every ebuild that does this would
+have to be manually edited.
 </p>
 
 <p>
-	The solution is <c>use.mask</c>, which is documented in
-	<uri link="::profiles/use.mask/"/>. Each profile can have a <c>use.mask</c>
-	file which can be used to forcibly disable certain USE flags on a given
-	arch (or subarch, or subprofile). So, if the <c>fakemedia</c> USE flag was
-	use.masked on every non-x86 profile, the following would be totally legal
-	and wouldn't break anything:
+The solution is <c>use.mask</c>, which is documented in
+<uri link="::profiles/use.mask/"/>. Each profile can have a <c>use.mask</c>
+file which can be used to forcibly disable certain USE flags on a given
+arch (or subarch, or subprofile). So, if the <c>fakemedia</c> USE flag was
+use.masked on every non-x86 profile, the following would be totally legal
+and wouldn't break anything:
 </p>
 
 <codesample lang="ebuild">
@@ -102,16 +102,16 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
 </codesample>
 
 <p>
-	Users of non-x86 would see the following when doing
-	<c>emerge -pv vplayer</c>:
+Users of non-x86 would see the following when doing
+<c>emerge -pv vplayer</c>:
 </p>
 
 <pre>
-	[ebuild   R   ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz
+[ebuild   R   ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz
 </pre>
 
 <p>
-	To get a flag added to <c>use.mask</c>, ask the relevant arch team.
+To get a flag added to <c>use.mask</c>, ask the relevant arch team.
 </p>
 
 </body>
@@ -122,28 +122,28 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
 <body>
 
 <p>
-	USE flags are categorised as either local or global. A global USE flag must
-	satisfy several criteria:
+USE flags are categorised as either local or global. A global USE flag must
+satisfy several criteria:
 </p>
 
 <ul>
 	<li>It is used by many different packages, at least 5 seems to be agreed
 		upon.</li>
-  <li>It has a general non-specific purpose.</li>
+	<li>It has a general non-specific purpose.</li>
 </ul>
 
 <p>
-	The second point is important. If the effect of the USE flag upon
-	<c>pkg-one</c> is substantially different from the effect it has upon
-	<c>pkg-two</c>, then the flag is not a suitable candidate for being made a
-	global flag. In particular, note that if <c>client</c> and <c>server</c>
-	USE flags are ever introduced, they can not be global USE flags for this
-	reason.
+The second point is important. If the effect of the USE flag upon
+<c>pkg-one</c> is substantially different from the effect it has upon
+<c>pkg-two</c>, then the flag is not a suitable candidate for being made a
+global flag. In particular, note that if <c>client</c> and <c>server</c>
+USE flags are ever introduced, they can not be global USE flags for this
+reason.
 </p>
 
 <p>
-	Before introducing a new global USE flag, it must be discussed on the
-	gentoo-dev mailing list.
+Before introducing a new global USE flag, it must be discussed on the
+gentoo-dev mailing list.
 </p>
 
 </body>
@@ -153,23 +153,23 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
 <title>USE Flag Descriptions</title>
 <body>
 <p>
-	All USE flags must be described in either <c>use.desc</c> in the
-	<c>profiles/</c> directory or <c>metadata.xml</c> in the package's
-	directory. See <c>man portage</c> or the comments in these files for an
-	explanation of the format. Remember to keep these files sorted. The file
-	<c>use.local.desc</c> is automatically generated from entries in the
-	package's <c>metadata.xml</c> and may be used by tools that parse the tree.
-	Since <c>use.local.desc</c> is automatically generated it must never be
-	manually editted in the tree.
-	See <uri link="https://www.gentoo.org/glep/glep-0056.html">GLEP 56</uri>
-	for more info.
+All USE flags must be described in either <c>use.desc</c> in the
+<c>profiles/</c> directory or <c>metadata.xml</c> in the package's
+directory. See <c>man portage</c> or the comments in these files for an
+explanation of the format. Remember to keep these files sorted. The file
+<c>use.local.desc</c> is automatically generated from entries in the
+package's <c>metadata.xml</c> and may be used by tools that parse the tree.
+Since <c>use.local.desc</c> is automatically generated it must never be
+manually editted in the tree.
+See <uri link="https://www.gentoo.org/glep/glep-0056.html">GLEP 56</uri>
+for more info.
 </p>
 <p>
-	The exceptions to this are <c>USE_EXPAND</c> flags, which must be
-	documented in the <c>profiles/desc/</c> directory. One file per
-	<c>USE_EXPAND</c> variable is required, which must contain descriptions of
-	the possible values this variable can take. See the comments in these files
-	for the format, and remember to keep them sorted.
+The exceptions to this are <c>USE_EXPAND</c> flags, which must be
+documented in the <c>profiles/desc/</c> directory. One file per
+<c>USE_EXPAND</c> variable is required, which must contain descriptions of
+the possible values this variable can take. See the comments in these files
+for the format, and remember to keep them sorted.
 </p>
 </body>
 </section>
@@ -178,16 +178,16 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
 <title>Conflicting USE Flags</title>
 <body>
 <p>
-	Occasionally, ebuilds will have conflicting USE flags for functionality.
-	Checking for them and returning an error is <e>not</e> a viable solution.
-	Instead, you must pick one of the USE flags in conflict to favour and should
-	alert the user that a particular flag is being used instead.
+Occasionally, ebuilds will have conflicting USE flags for functionality.
+Checking for them and returning an error is <e>not</e> a viable solution.
+Instead, you must pick one of the USE flags in conflict to favour and should
+alert the user that a particular flag is being used instead.
 </p>
 
 <p>
-	One example comes from the <c>mail-mta/msmtp</c> ebuilds. The package can
-	use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because
-	GnuTLS is more featureful than OpenSSL, it is favoured:
+One example comes from the <c>mail-mta/msmtp</c> ebuilds. The package can
+use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because
+GnuTLS is more featureful than OpenSSL, it is favoured:
 </p>
 
 <codesample lang="ebuild">
@@ -211,26 +211,26 @@ src_compile() {
 </codesample>
 
 <p>
-	In some exceptional cases, above policy would break reverse USE
-	dependencies. To avoid this, the ebuild can specify allowed USE flag
-	combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
-	<uri link="::ebuild-writing/eapi/#eapi=4" /> for a description
-	of its syntax.
+In some exceptional cases, above policy would break reverse USE
+dependencies. To avoid this, the ebuild can specify allowed USE flag
+combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
+<uri link="::ebuild-writing/eapi/#eapi=4" /> for a description
+of its syntax.
 </p>
 
 <p>
-	For example, if a package <c>dev-libs/foo</c> can be built with either
-	<c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of
-	the flags would break packages that depend on either <c>dev-libs/foo[a]</c>
-	or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify
-	<c>REQUIRED_USE="a? ( !b )"</c> in this case.
+For example, if a package <c>dev-libs/foo</c> can be built with either
+<c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of
+the flags would break packages that depend on either <c>dev-libs/foo[a]</c>
+or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify
+<c>REQUIRED_USE="a? ( !b )"</c> in this case.
 </p>
 
 <note>
-	In order to avoid forcing users to micro-manage flags too much,
-	<c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy
-	whenever it is possible to do a build that will presumably suit the user's
-	needs.
+In order to avoid forcing users to micro-manage flags too much,
+<c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy
+whenever it is possible to do a build that will presumably suit the user's
+needs.
 </note>
 </body>
 </section>
@@ -240,32 +240,32 @@ src_compile() {
 <body>
 
 <p>
-	The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>L10N</c> variables
-	are automatically expanded into USE flags. These are known as
-	<c>USE_EXPAND</c> variables. If the user has <c>L10N="en fr"</c> in
-	<c>make.conf</c>, for example, then <c>USE="l10n_en l10n_fr"</c> will
-	automatically be set by Portage.
+The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>L10N</c> variables
+are automatically expanded into USE flags. These are known as
+<c>USE_EXPAND</c> variables. If the user has <c>L10N="en fr"</c> in
+<c>make.conf</c>, for example, then <c>USE="l10n_en l10n_fr"</c> will
+automatically be set by Portage.
 </p>
 
 <p>
-	The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of
-	Portage 2.0.51.20. This must not be modified without discussion on the
-	gentoo-dev list, and it must not be modified in any subprofile.
+The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of
+Portage 2.0.51.20. This must not be modified without discussion on the
+gentoo-dev list, and it must not be modified in any subprofile.
 </p>
 
 <p>
-	The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>)
-	will automatically be set as a USE flag as well. See
-	<c>profiles/arch.list</c> for a full list of valid architecture keywords,
-	and <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri>
-	for an explanation of the format.
+The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>)
+will automatically be set as a USE flag as well. See
+<c>profiles/arch.list</c> for a full list of valid architecture keywords,
+and <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri>
+for an explanation of the format.
 </p>
 
 <warning>
-	It is a common misconception that the architecture variable is somehow
-	related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords
-	on <c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there
-	are no <c>~arch</c> USE flags, so don't try <c>if use ~x86</c>.
+It is a common misconception that the architecture variable is somehow
+related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords
+on <c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there
+are no <c>~arch</c> USE flags, so don't try <c>if use ~x86</c>.
 </warning>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Ulrich Müller]

commit:     ffdbcac1b3652fec02efcc695ba15409bfda19f3
Author:     Mikle Kolyada <zlogene <AT> gentoo <DOT> org>
AuthorDate: Sat Jun 16 21:57:42 2018 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jun 22 18:24:13 2018 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ffdbcac1

general-concepts/use-flags: deprecate LINGUAS in favour of L10N

 general-concepts/use-flags/text.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 88da628..0e46546 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -240,10 +240,10 @@ src_compile() {
 <body>
 
 <p>
-	The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>LINGUAS</c> variables
+	The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>L10N</c> variables
 	are automatically expanded into USE flags. These are known as
-	<c>USE_EXPAND</c> variables. If the user has <c>LINGUAS="en fr"</c> in
-	<c>make.conf</c>, for example, then <c>USE="linguas_en linguas_fr"</c> will
+	<c>USE_EXPAND</c> variables. If the user has <c>L10N="en fr"</c> in
+	<c>make.conf</c>, for example, then <c>USE="l10n_en l10n_fr"</c> will
 	automatically be set by Portage.
 </p>
 

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Markos Chandras]

commit:     5a09fd6882abf4554652116a5123ee96d68dc258
Author:     Manuel Rüger <mrueg <AT> gentoo <DOT> org>
AuthorDate: Fri Apr  4 15:32:47 2014 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Fri Apr  4 15:32:47 2014 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=5a09fd68

Fix anchor link to eapi

---
 general-concepts/use-flags/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 2e20593..f187808 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -215,7 +215,7 @@ src_compile() {
 	In some exceptional cases, above policy would break reverse USE
 	dependencies. To avoid this, the ebuild can specify allowed USE flag
 	combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
-	<uri link="::ebuild-writing/eapi/#eapi=&quot;4&quot;" /> for a description
+	<uri link="::ebuild-writing/eapi/#eapi=4" /> for a description
 	of its syntax.
 </p>
 

[gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/

[Torsten Veller]

commit:     327865a60a425ab940f2a46eff09d7de9756a9e6
Author:     Torsten Veller <tove <AT> gentoo <DOT> org>
AuthorDate: Thu Apr  5 14:19:53 2012 +0000
Commit:     Torsten Veller <tove <AT> gentoo <DOT> org>
CommitDate: Thu Apr  5 14:19:53 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=327865a6

Fix typo: make.default -> make.defaults (#410835)

---
 general-concepts/use-flags/text.xml |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 5f472a6..85523fc 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -249,7 +249,7 @@ src_compile() {
 </p>
 
 <p>
-	The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.default</c> as of
+	The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of
 	Portage 2.0.51.20. This must not be modified without discussion on the
 	gentoo-dev list, and it must not be modified in any subprofile.
 </p>