From: "Göktürk Yüksek" <gokturk@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/
Date: Wed, 22 May 2019 19:37:26 +0000 (UTC) [thread overview]
Message-ID: <1558553642.a5f4ce3b3a39db8f6944ba9f1a1c7fb88f2f6990.gokturk@gentoo> (raw)
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>
next reply other threads:[~2019-05-22 19:37 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-22 19:37 Göktürk Yüksek [this message]
-- strict thread matches above, loose matches on Subject: below --
2024-12-09 18:29 [gentoo-commits] proj/devmanual:master commit in: general-concepts/use-flags/ Ulrich Müller
2023-08-22 6:03 Ulrich Müller
2022-02-21 21:40 Sam James
2021-08-01 2:13 Sam James
2021-08-01 2:08 Sam James
2021-04-10 7:03 Ulrich Müller
2021-04-10 7:03 Ulrich Müller
2021-04-10 7:03 Ulrich Müller
2021-04-02 7:00 Ulrich Müller
2019-05-24 8:40 Ulrich Müller
2019-05-22 19:37 Göktürk Yüksek
2019-05-22 19:37 Göktürk Yüksek
2019-05-22 19:37 Göktürk Yüksek
2019-05-22 19:37 Göktürk Yüksek
2018-06-22 18:25 Ulrich Müller
2014-04-06 15:51 Markos Chandras
2012-04-05 14:22 Torsten Veller
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=1558553642.a5f4ce3b3a39db8f6944ba9f1a1c7fb88f2f6990.gokturk@gentoo \
--to=gokturk@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