aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xbin/gen-eclass-html.sh4
-rw-r--r--devbook.xsl4
-rw-r--r--ebuild-maintenance/maintenance-tasks/text.xml9
-rw-r--r--ebuild-writing/common-mistakes/text.xml6
-rw-r--r--ebuild-writing/eapi/text.xml6
-rw-r--r--ebuild-writing/file-format/text.xml10
-rw-r--r--ebuild-writing/functions/src_unpack/rpm-sources/text.xml2
-rw-r--r--ebuild-writing/using-eclasses/text.xml2
-rw-r--r--ebuild-writing/variables/text.xml17
-rw-r--r--eclass-writing/text.xml6
-rw-r--r--general-concepts/use-flags/text.xml305
-rw-r--r--quickstart/text.xml56
12 files changed, 235 insertions, 192 deletions
diff --git a/bin/gen-eclass-html.sh b/bin/gen-eclass-html.sh
index 65b70f0..db61319 100755
--- a/bin/gen-eclass-html.sh
+++ b/bin/gen-eclass-html.sh
@@ -18,11 +18,11 @@ IFS='' read -r -d '' FOOTER << 'EOF'
<div class="row">
<div class="col-xs-2 col-sm-3 col-md-2"><ul class="footerlinks three-icons">
<li><a href="http://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li>
-<li><a href="https://plus.google.com/+Gentoo" title="+Gentoo on Google+"><span class="fa fa-google-plus fa-fw"></span></a></li>
<li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li>
+<li></li>
</ul></div>
<div class="col-xs-10 col-sm-9 col-md-10">
-<strong>Copyright (C) 2001-2019 Gentoo Foundation, Inc.</strong><br><small>
+<strong>Copyright (C) 2001-2019 Gentoo Authors</strong><br><small>
Gentoo is a trademark of the Gentoo Foundation, Inc.
The text of this document is distributed under the
<a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
diff --git a/devbook.xsl b/devbook.xsl
index 4a47b6b..8fba56c 100644
--- a/devbook.xsl
+++ b/devbook.xsl
@@ -550,12 +550,12 @@
<div class="col-xs-2 col-sm-3 col-md-2">
<ul class="footerlinks three-icons">
<li><a href="http://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li>
- <li><a href="https://plus.google.com/+Gentoo" title="+Gentoo on Google+"><span class="fa fa-google-plus fa-fw"></span></a></li>
<li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li>
+ <li></li>
</ul>
</div>
<div class="col-xs-10 col-sm-9 col-md-10">
- <strong>Copyright (C) 2001-2019 Gentoo Foundation, Inc.</strong><br />
+ <strong>Copyright (C) 2001-2019 Gentoo Authors</strong><br />
<small>
Gentoo is a trademark of the Gentoo Foundation, Inc.
The text of this document is distributed under the
diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml
index a434fb5..06634b8 100644
--- a/ebuild-maintenance/maintenance-tasks/text.xml
+++ b/ebuild-maintenance/maintenance-tasks/text.xml
@@ -34,11 +34,10 @@ select all possible fields, then submit the query. For you lazy people, click
In general, the Gentoo repository should only be used for storing
<path>.ebuild</path> files, as well as any relatively small companion
files, such as patches or sample configuration files. These types of
-files should be placed in the
-<path>/usr/portage/mycat/mypkg/files</path> directory to keep the main
-<path>mycat/mypkg</path> directory uncluttered. Exceptions to this
-rule are for larger patch files (we recommend this for patches above
-20KB) which should be distributed as tarballs via the
+files should be placed in the <path>mycat/mypkg/files</path> directory
+to keep the main <path>mycat/mypkg</path> directory uncluttered.
+Exceptions to this rule are for larger patch files (we recommend this
+for patches above 20KB) which should be distributed as tarballs via the
<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo
mirror system</uri> so that people do not waste excessive amounts of
bandwidth and hard drive space. Also, you should not add binary
diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml
index 1658f49..869676e 100644
--- a/ebuild-writing/common-mistakes/text.xml
+++ b/ebuild-writing/common-mistakes/text.xml
@@ -163,7 +163,7 @@ The first two lines <e>must</e> look like this:
</p>
<pre caption="Valid Header">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
</pre>
@@ -300,14 +300,14 @@ Another common mistake users make when submitting ebuilds is supplying an
invalid license. For example, <c>GPL</c> is not a valid license. You need to
specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the
license you use in the <c>LICENSE</c> field is something that exists in
-<path>/usr/portage/licenses</path>. As a tip, check the <path>COPYING</path>
+the <path>licenses</path> directory. As a tip, check the <path>COPYING</path>
in a source tarball for the license. If a package does not specify it
uses <c>GPL-1</c> or <c>GPL-2</c>, it is very likely it uses <c>GPL-2</c>.
</p>
<p>
If the license for the package you submit is unique and not in
-<path>/usr/portage/licenses/</path>, then you must submit the new license in a
+<path>licenses/</path>, then you must submit the new license in a
separate file.
</p>
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
index d375422..884f3c1 100644
--- a/ebuild-writing/eapi/text.xml
+++ b/ebuild-writing/eapi/text.xml
@@ -42,7 +42,7 @@ Most developers prefer to set the EAPI version without quotes. However, the PMS
</note>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=6
@@ -117,7 +117,7 @@ src_compile() {
</important>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=1
@@ -523,7 +523,7 @@ DEPEND="
</p>
<p>Example:</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=4
diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
index 95f55ac..f9e4bd9 100644
--- a/ebuild-writing/file-format/text.xml
+++ b/ebuild-writing/file-format/text.xml
@@ -26,10 +26,10 @@ discouraged, but technically valid.
<note>
This is the same as
-<uri link="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278">
-IEEE Std 1003.1-2013, section 3.278</uri>, with the exception of the period
-character and with the addition of the plus character to keep GTK+ and friends
-happy.
+<uri link="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282">
+IEEE Std 1003.1-2013, section 3.282 (Portable Filename Character Set)</uri>,
+with the exception of the period character and with the addition of the plus
+character to keep GTK+ and friends happy.
</note>
<p>
@@ -151,7 +151,7 @@ header.txt</uri></c> in the top directory of the Gentoo repository.
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
</codesample>
diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
index c40bcae..d597d99 100644
--- a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
+++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml
@@ -52,7 +52,7 @@ patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.ebuild</c>.
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI="6"
diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml
index 0c13896..bd50796 100644
--- a/ebuild-writing/using-eclasses/text.xml
+++ b/ebuild-writing/using-eclasses/text.xml
@@ -32,7 +32,7 @@ uses three eclasses:
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index e63c8ff..811be44 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -370,23 +370,6 @@ SRC_URI="https://example.com/files/${P}-core.tar.bz2
doc? ( https://example.com/files/${P}/${P}-docs.tar.bz2 )"
</codesample>
-<p>
-If a <c>USE_EXPAND</c> variable is used to control whether certain optional
-components are installed, the correct thing to do if the variable is unset is
-generally to install <e>all</e> available components.
-</p>
-
-<codesample lang="ebuild">
-SRC_URI="https://example.com/files/${P}-core.tar.bz2
- examplecards_foo? ( https://example.com/files/${P}-foo.tar.bz2 )
- examplecards_bar? ( https://example.com/files/${P}-bar.tar.bz2 )
- examplecards_baz? ( https://example.com/files/${P}-baz.tar.bz2 )
- !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
- https://example.com/files/${P}-foo.tar.bz2
- https://example.com/files/${P}-bar.tar.bz2
- https://example.com/files/${P}-baz.tar.bz2 ) ) )"
-</codesample>
-
</body>
</subsection>
diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml
index 352e026..ee7d5d0 100644
--- a/eclass-writing/text.xml
+++ b/eclass-writing/text.xml
@@ -612,7 +612,7 @@ a single function, <c>domacosapp</c>.
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: macosapp.eclass
@@ -699,7 +699,7 @@ something like the following:
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: jmake.eclass
@@ -760,7 +760,7 @@ for an eclass to invoke die from the global scope. For example:
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: eapi-die.eclass
diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
index 0e46546..74cb45d 100644
--- a/general-concepts/use-flags/text.xml
+++ b/general-concepts/use-flags/text.xml
@@ -5,61 +5,138 @@
<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.
+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
- setting or unsetting a USE flag between merge and unmerge has no effect.
+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>
<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
+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>
+
+<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>
+
+<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>
+
+<section>
<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 +144,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 +160,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 +179,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 +199,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 +230,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 +255,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">
@@ -206,31 +283,31 @@ src_compile() {
# Other stuff
${myconf}
- emake || die "make failed"
+ emake
}
</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 +317,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>
diff --git a/quickstart/text.xml b/quickstart/text.xml
index 3e76a2e..d913374 100644
--- a/quickstart/text.xml
+++ b/quickstart/text.xml
@@ -34,7 +34,7 @@ can see real ebuilds in the main tree).
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=6
@@ -43,7 +43,7 @@ DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"
-LICENSE="GPL-2"
+LICENSE="GPL-2+"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
@@ -111,7 +111,8 @@ name and version <d/> in this case, it would be <c>ctags-5.5.4</c>.
</p>
<p>
-The <c>LICENSE</c> is <c>GPL-2</c> (the GNU General Public License version 2).
+The <c>LICENSE</c> is <c>GPL-2+</c> (the GNU General Public License version 2
+or (at your option) any later version).
</p>
<p>
@@ -203,7 +204,7 @@ Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>:
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=5
@@ -224,11 +225,6 @@ DEPEND="${RDEPEND}
src_configure() {
econf --with-popt
}
-
-src_install() {
- emake DESTDIR="${D}" install
- dodoc README CHANGES
-}
</codesample>
<p>
@@ -240,7 +236,9 @@ variables <d/> see
</p>
<p>
-Again, we define <c>src_configure</c> and <c>src_install</c> functions.
+We define <c>src_configure</c> only. <c>src_install</c> does not need to
+be defined since the default implementation calling <c>emake install</c>
+and installing common documentation files works correctly for the package.
</p>
<p>
@@ -259,20 +257,15 @@ compile-time dependencies, and the <c>RDEPEND</c> lists runtime dependencies. Se
<body>
<p>
Often we need to apply patches. This is done in the <c>src_prepare</c>
-function using the <c>epatch</c> helper function. To use <c>epatch</c>
-one must first tell Portage that the <c>epatch</c> eclass (an eclass is
-like a library) is required <d/>
-this is done via <c>inherit epatch</c> at the top of the ebuild. Here's
-<c>app-misc/detox/detox-1.1.0.ebuild</c>:
+function using the <c>eapply</c> helper function. To use <c>eapply</c>
+one must use EAPI 7. Here's <c>app-misc/detox/detox-1.1.0.ebuild</c>:
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
-EAPI=5
-
-inherit epatch
+EAPI=7
DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
@@ -288,18 +281,13 @@ DEPEND="${RDEPEND}
sys-devel/bison"
src_prepare() {
- epatch "${FILESDIR}"/${P}-destdir.patch \
+ eapply "${FILESDIR}"/${P}-destdir.patch \
"${FILESDIR}"/${P}-parallel_build.patch
}
src_configure() {
econf --with-popt
}
-
-src_install() {
- emake DESTDIR="${D}" install
- dodoc README CHANGES
-}
</codesample>
<p>
@@ -324,7 +312,7 @@ replacement iconv for <c>libc</c> implementations which don't have their own.
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=5
@@ -333,7 +321,7 @@ DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
HOMEPAGE="https://www.gnu.org/software/libiconv/"
SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"
-LICENSE="LGPL-2.1"
+LICENSE="LGPL-2+ GPL-3+"
SLOT="0"
KEYWORDS="~amd64 ~ppc ~sparc ~x86"
IUSE="nls"
@@ -343,10 +331,6 @@ DEPEND="!sys-libs/glibc"
src_configure() {
econf $(use_enable nls)
}
-
-src_install() {
- emake DESTDIR="${D}" install
-}
</codesample>
<p>
@@ -367,18 +351,18 @@ Another more complicated example, this time based upon
</p>
<codesample lang="ebuild">
-# Copyright 1999-2019 Gentoo Foundation
+# Copyright 1999-2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
-EAPI=5
+EAPI=7
-inherit epatch desktop
+inherit desktop
DESCRIPTION="A lightweight email client and newsreader"
HOMEPAGE="https://sylpheed.good-day.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
-LICENSE="GPL-2"
+LICENSE="GPL-2+ LGPL-2.1+"
SLOT="0"
KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86"
IUSE="crypt imlib ipv6 ldap nls pda ssl xface"
@@ -397,7 +381,7 @@ DEPEND="${RDEPEND}
nls? ( >=sys-devel/gettext-0.12.1 )"
src_prepare() {
- epatch "${FILESDIR}"/${PN}-namespace.diff \
+ eapply "${FILESDIR}"/${PN}-namespace.diff \
"${FILESDIR}"/${PN}-procmime.diff
}