[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Markos Chandras]

commit:     14449d40dcc275f4c113e6e976f1d72671aff7cd
Author:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
AuthorDate: Sat Nov  3 21:59:34 2012 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Sun Nov 11 19:32:24 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=14449d40

ebuild-writing/variables: Add a note that IUSE must always be present

---
 ebuild-writing/variables/text.xml |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 379ca00..f825c06 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -309,6 +309,9 @@ Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
 USE flags used only within inherited eclasses within the ebuild's IUSE. Also
 note that it's really really broken in portage versions before 2.0.51.
 </p>
+<important>
+You must always add the IUSE variable in your ebuild even if it is empty.
+</important>
 
 <p>
 Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Mueller]

commit:     a0580c23f0e7bf4b871e74efe742ff466e771a3d
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Nov 24 14:40:04 2012 +0000
Commit:     Ulrich Mueller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Nov 24 14:53:01 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=a0580c23

ebuild-writing/variables: Remove obsolete note about Portage version

---
 ebuild-writing/variables/text.xml |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index f825c06..1f0f3f5 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -306,8 +306,7 @@ SRC_URI="http://example.com/files/${P}-core.tar.bz2
 
 <p>
 Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
-USE flags used only within inherited eclasses within the ebuild's IUSE. Also
-note that it's really really broken in portage versions before 2.0.51.
+USE flags used only within inherited eclasses within the ebuild's IUSE.
 </p>
 <important>
 You must always add the IUSE variable in your ebuild even if it is empty.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Dirkjan Ochtman]

commit:     bcd3510642eb31549aaed5ab0102abccf120c867
Author:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
AuthorDate: Wed May 15 13:11:27 2013 +0000
Commit:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
CommitDate: Wed May 15 13:11:27 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=bcd35106

Mention REQUIRED_USE in ebuild-defined variables list.

---
 ebuild-writing/variables/text.xml |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 5268af2..b3c5fb4 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -183,6 +183,14 @@ The following variables may or must be defined by every ebuild.
     </ti>
   </tr>
   <tr>
+    <ti><c>REQUIRED_USE</c></ti>
+    <ti>
+    A list of assertions that must be met by the configuration of
+    <c>USE</c> flags to be valid for this ebuild. (Requires
+    <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.)
+    </ti>
+  </tr>
+  <tr>
     <ti><c>RESTRICT</c></ti>
     <ti>
     A space-delimited list of portage features to restrict.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Dirkjan Ochtman]

commit:     e7abb2f868c272c9c3878c727e479d1211db378d
Author:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
AuthorDate: Wed May 15 13:39:19 2013 +0000
Commit:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
CommitDate: Wed May 15 13:39:19 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=e7abb2f8

Mention DOCS in ebuild-defined variables list.

---
 ebuild-writing/variables/text.xml |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index f557ffd..d2e97cb 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -237,6 +237,15 @@ The following variables may or must be defined by every ebuild.
     for now.
     </ti>
   </tr>
+  <tr>
+    <ti><c>DOCS</c></ti>
+    <ti>
+    An array or space-delimited list of documentation files for
+    the default src_install function to install using dodoc. If
+    undefined, a reasonable default list is used. (Requires
+    <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.)
+    </ti>
+  </tr>
 </table>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Dirkjan Ochtman]

commit:     17037830a47887439123c3cb6c39156728dcd2ac
Author:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
AuthorDate: Wed May 15 13:32:02 2013 +0000
Commit:     Dirkjan Ochtman <djc <AT> gentoo <DOT> org>
CommitDate: Wed May 15 13:32:02 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=17037830

Mention PROPERTIES in ebuild-defined variables list.

---
 ebuild-writing/variables/text.xml |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index b3c5fb4..f557ffd 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -229,6 +229,14 @@ The following variables may or must be defined by every ebuild.
     value for this variable if it is the same as the default value.
     </ti>
   </tr>
+  <tr>
+    <ti><c>PROPERTIES</c></ti>
+    <ti>
+    A space-delimited list of properties, with conditional
+    syntax support. <c>interactive</c> is the only valid value
+    for now.
+    </ti>
+  </tr>
 </table>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Mike Frysinger]

commit:     fc94b7c5ee7672096abbfead15f956b887c6d5ba
Author:     Mike Frysinger <vapier <AT> gentoo <DOT> org>
AuthorDate: Fri Aug  7 05:08:38 2015 +0000
Commit:     Mike Frysinger <vapier <AT> gentoo <DOT> org>
CommitDate: Fri Aug  7 05:08:38 2015 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fc94b7c5

variables: SRC_URI: document the -> syntax

 ebuild-writing/variables/text.xml | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index a31baa2..fd749c0 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -323,6 +323,30 @@ SRC_URI="http://example.com/files/${P}-core.tar.bz2
 
 </body>
 </subsection>
+
+<subsection>
+<title>Renaming Sources</title>
+<body>
+
+<p>
+Sometimes the upstream URI uses generic names that can easily clash with other
+packages when creating a single mirror. Using the <c>-&gt;</c> syntax allows
+you to rename the file when it's fetched from upstream for storing on mirrors
+and in the local distdir.
+</p>
+
+<p>
+Here we download a file from upstream which has a plain name like
+<c>1.0.tar.gz</c> and save/mirror it with a better name like
+<c>thepackage-1.0.tar.gz</c>.
+</p>
+
+<codesample lang="ebuild">
+SRC_URI="http://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
+</codesample>
+
+</body>
+</subsection>
 </section>
 
 <section>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     844bedc6b891c1cbc0497d7d7ad54ec7922639ba
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Dec  8 20:05:02 2015 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Dec  8 20:05:02 2015 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=844bedc6

ebuild-writing/variables: Clarify wording for length of DESCRIPTION.

Bug: 562806

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index fd749c0..a9671de 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -130,7 +130,7 @@ The following variables may or must be defined by every ebuild.
   <tr>
     <ti><c>DESCRIPTION</c></ti>
     <ti>
-    A short (less than 80 characters) description of the package's
+    A short (not more than 80 characters) description of the package's
     purpose. Mandatory.
     </ti>
   </tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     d24b59bd14a563baeb99b8465e4cc3e9b4d22d2b
Author:     Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu>
AuthorDate: Wed May  4 08:09:00 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu>
CommitDate: Wed May  4 09:08:15 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d24b59bd

ebuild-writing/variables: add HOME to the list of read-only variables

Per PMS Section 11.1 [0], HOME is a read-only environment variable.

[0] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-11900011.1

Signed-off-by: Göktürk Yüksek <gokturk <AT> binghamton.edu>

 ebuild-writing/variables/text.xml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index a9671de..ef15347 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -90,6 +90,14 @@ them.
     </ti>
   </tr>
   <tr>
+    <ti><c>HOME</c></ti>
+    <ti>
+      Path to a temporary directory for use by any programs invoked by
+      an ebuild that may read or modify the home directory. Value:
+      <c>"${PORTAGE_BUILDDIR}/homedir"</c>.
+    </ti>
+  </tr>
+  <tr>
     <ti><c>ROOT</c></ti>
     <ti>
       Path to the root directory. When not using <c>${D}</c>,

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Mike Gilbert]

commit:     3a3520925c5ce02f430138e1e21a13225299076a
Author:     Mike Gilbert <floppym <AT> gentoo <DOT> org>
AuthorDate: Sun May  8 17:40:25 2016 +0000
Commit:     Mike Gilbert <floppym <AT> gentoo <DOT> org>
CommitDate: Sun May  8 19:32:00 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3a352092

ebuild-writing/variables: better describe ROOT

The current description of ROOT makes no sense and just confuses people.
The new description is paraphrased from PMS.

 ebuild-writing/variables/text.xml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index ef15347..9027cad 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -100,8 +100,9 @@ them.
   <tr>
     <ti><c>ROOT</c></ti>
     <ti>
-      Path to the root directory. When not using <c>${D}</c>,
-      always prepend <c>${ROOT}</c> to the path.
+      The absolute path to the root directory into which the package is to be
+      merged. Use this when referring to installed files in <c>pkg_*</c>
+      functions. Never use this in <c>src_*</c> functions.
     </ti>
   </tr>
   <tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     d1a7be9d1bf8138fe3476a579ce0af004979c914
Author:     Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu>
AuthorDate: Sun May 15 02:34:54 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu>
CommitDate: Wed May 18 06:49:39 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d1a7be9d

ebuild-writing/variables: add a section to explain the ROOT variable #144332

The text is originally based on the patch provided by Thilo Bangert
<bangert at gentoo.org> in the bug. It is revised and expanded to
mention the use of ROOT in cross-compiling environments as explained
in PMS Table 11.1.

Gentoo-Bug: https://bugs.gentoo.org/144332
Signed-off-by: Göktürk Yüksek <gokturk <AT> binghamton.edu>

 ebuild-writing/variables/text.xml | 55 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 9027cad..dc152e1 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -101,8 +101,8 @@ them.
     <ti><c>ROOT</c></ti>
     <ti>
       The absolute path to the root directory into which the package is to be
-      merged. Use this when referring to installed files in <c>pkg_*</c>
-      functions. Never use this in <c>src_*</c> functions.
+      merged. Only allowed in pkg_* phases. See
+      <uri link="::ebuild-writing/variables#ROOT"/>
     </ti>
   </tr>
   <tr>
@@ -393,6 +393,57 @@ GLEP 23</uri> for details.
 </section>
 
 <section>
+<title>ROOT</title>
+<body>
+
+<p>
+The idea behind <c>ROOT</c> is that one can build a system with
+<c>ROOT=/somewhere</c> and then chroot into it or tar up
+<c>/somewhere</c> as a system image. It is not designed to allow the
+user to run <c>/somewhere/usr/bin/foo</c>.
+</p>
+
+<p>
+Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It
+can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may
+be different when merging a binary package. For example, a binary
+package may be built with <c>ROOT=/</c> and then installed onto a
+system using <c>ROOT=/somewhere</c>.
+</p>
+
+<p>
+When building a package, <c>ROOT</c> should not be used to satisfy the
+required dependencies on libraries, headers files etc. Instead, the
+files on the build system should be specified using <c>/</c>.
+</p>
+
+<p>
+In a cross compiling environment, ebuilds must not call any of the
+binaries inside <c>ROOT</c> since they may not be executable on the
+build system.
+</p>
+
+<p>
+Below is an example of an ebuild that uses <c>ROOT</c> in
+<c>pkg_postinst()</c> to conditionally print an error message if an
+old and obsolete configuration file still exists:
+
+<codesample lang="ebuild">
+pkg_postinst() {
+	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
+		ewarn "You still have the obsolete config file "
+		ewarn "    ${ROOT}/etc/oldconfig."
+		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
+		ewarn "and remove ${ROOT}/etc/oldconfig."
+	fi
+}
+</codesample>
+</p>
+
+</body>
+</section>
+
+<section>
 <title>Version and Name Formatting Issues</title>
 <body>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     9493a374b90a484b8f852aadeb0e333775767e65
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Thu May 19 05:23:35 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu May 19 05:23:35 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9493a374

ebuild-writing/variables: do not rely on package manager specific values

For predefined read-only variables, ebuild authors must not make
assumptions about their values based on a specific package manager
implementation. Clarify the section accordingly.

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index dc152e1..3f99cfb 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -16,8 +16,9 @@ which are of use throughout the ebuild.
 <body>
 
 <p>
-The following variables are defined for you. You must not attempt to set
-them.
+The following variables are defined for you. You must not attempt to
+set them. Developers must not rely on package manager specific values
+for these variables when writing ebuilds.
 </p>
 
 <table>
@@ -64,14 +65,14 @@ them.
     <ti><c>FILESDIR</c></ti>
     <ti>
       Path to the ebuild's <c>files/</c> directory, commonly used
-      for small patches and files. Value:
+      for small patches and files. For example:
       <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>.
     </ti>
   </tr>
   <tr>
     <ti><c>WORKDIR</c></ti>
     <ti>
-      Path to the ebuild's root build directory. Value:
+      Path to the ebuild's root build directory. For example:
       <c>"${PORTAGE_BUILDDIR}/work"</c>.
     </ti>
   </tr>
@@ -79,13 +80,13 @@ them.
     <ti><c>T</c></ti>
     <ti>
        Path to a temporary directory which may be used by the
-       ebuild. Value: <c>"${PORTAGE_BUILDDIR}/temp"</c>.
+       ebuild. For example: <c>"${PORTAGE_BUILDDIR}/temp"</c>.
     </ti>
   </tr>
   <tr>
     <ti><c>D</c></ti>
     <ti>
-      Path to the temporary install directory. Value:
+      Path to the temporary install directory. For example:
       <c>"${PORTAGE_BUILDDIR}/image"</c>.
     </ti>
   </tr>
@@ -93,7 +94,7 @@ them.
     <ti><c>HOME</c></ti>
     <ti>
       Path to a temporary directory for use by any programs invoked by
-      an ebuild that may read or modify the home directory. Value:
+      an ebuild that may read or modify the home directory. For example:
       <c>"${PORTAGE_BUILDDIR}/homedir"</c>.
     </ti>
   </tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     57778b90ee0f252bb4b295f3b0053e9a581b85fb
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Jun  1 14:42:02 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Jul  4 03:46:15 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=57778b90

ebuild-writing/variables: update wrt ROOT always ending in a trailing slash

Per PMS[0], ROOT must end in a trailing slash. Remove the trailing
slash characters ('/') that appear after ${ROOT} in the example and
add a note about it.

There is a future EAPI request to remove this trailing slash
(#465722). Suggest the use of '${EROOT%/}' for maximum compatibility.

[0] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-11900011.1

 ebuild-writing/variables/text.xml | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 3f99cfb..7368525 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -431,16 +431,27 @@ old and obsolete configuration file still exists:
 
 <codesample lang="ebuild">
 pkg_postinst() {
-	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
+	if [[ -e "${ROOT}etc/oldconfig" ]]; then
 		ewarn "You still have the obsolete config file "
-		ewarn "    ${ROOT}/etc/oldconfig."
-		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
-		ewarn "and remove ${ROOT}/etc/oldconfig."
+		ewarn "    ${ROOT}etc/oldconfig."
+		ewarn "Please migrate your settings to ${ROOT}etc/newconfig"
+		ewarn "and remove ${ROOT}etc/oldconfig."
 	fi
 }
 </codesample>
+
+The <c>ROOT</c> variable always ends in a trailing slash. Therefore,
+there is no need to prefix it with <c>/</c> when joining paths.
 </p>
 
+<note>
+Future EAPI may remove the trailing slash at the end per
+<uri link="https://bugs.gentoo.org/465772">Bug 465722</uri>.
+Developers can use <c>${ROOT%/}</c> to ensure maximum compatibility
+with both the current and the future EAPI.
+</note>
+
+
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     4150a2e7bb74bac2ca3d34c2b6dc741c70d9c6f0
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Jul 13 03:16:57 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jul 13 03:16:57 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4150a2e7

ebuild-writing/variables: s/prefix/suffix/ in the ROOT section

Reported-By: Mike Gilbert <floppym <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 7368525..a82220e 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -441,7 +441,7 @@ pkg_postinst() {
 </codesample>
 
 The <c>ROOT</c> variable always ends in a trailing slash. Therefore,
-there is no need to prefix it with <c>/</c> when joining paths.
+there is no need to suffix it with <c>/</c> when joining paths.
 </p>
 
 <note>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     0a988afa7e59e6b12b23adc19d9661b7bb3c0529
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Tue Oct 25 22:07:39 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Oct 25 22:07:39 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0a988afa

ebuild-writing/variables: add brief explanations for EPREFIX, ED, EROOT

Briefly mention the variables EPREFIX, ED, and EROOT by using the
definitions from the PMS.

 ebuild-writing/variables/text.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index a82220e..eb8770d 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -113,6 +113,24 @@ for these variables when writing ebuilds.
       fetched for the package are stored.
     </ti>
   </tr>
+  <tr>
+    <ti><c>EPREFIX</c></ti>
+    <ti>
+      The normalised offset-prefix path of an offset installation.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>ED</c></ti>
+    <ti>
+      Shorthand for <c>${D%/}${EPREFIX}/</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>EROOT</c></ti>
+    <ti>
+      Shorthand for <c>${ROOT%/}${EPREFIX}/</c>.
+    </ti>
+  </tr>
 </table>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     1d5e96b5ef5eb637ea7aaa477eaeca56fad9a4fe
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Tue Oct 25 22:30:59 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Oct 25 22:30:59 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1d5e96b5

ebuild-writing/variables: move the trailing slash issue to a separate section

The ROOT section talks about using ${ROOT%/}/ notation to accommodate
for the upcoming EAPI. The variables D, ED, and EROOT also end in a
trailing slash. Create a separate section to talk about this issue.

Suggested-By: David Seifert <soap <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index eb8770d..f402070 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -457,19 +457,8 @@ pkg_postinst() {
 	fi
 }
 </codesample>
-
-The <c>ROOT</c> variable always ends in a trailing slash. Therefore,
-there is no need to suffix it with <c>/</c> when joining paths.
 </p>
 
-<note>
-Future EAPI may remove the trailing slash at the end per
-<uri link="https://bugs.gentoo.org/465772">Bug 465722</uri>.
-Developers can use <c>${ROOT%/}</c> to ensure maximum compatibility
-with both the current and the future EAPI.
-</note>
-
-
 </body>
 </section>
 
@@ -565,5 +554,28 @@ follows.
 </body>
 </section>
 
+<section>
+<title>Trailing Slashes in Variables</title>
+<body>
+
+<p>
+The following variables always end in a trailing slash by default:
+<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Therefore, there is no
+need to suffix them with <c>/</c> when joining paths.
+</p>
+
+<note>
+Future EAPI may remove the trailing slash at the end per
+<uri link="https://bugs.gentoo.org/465772">Bug 465722</uri>.
+To ease the transition, and ensure maximum compatibility with both the
+current and the future EAPI, developers are encouraged to use the bash
+suffix removal for the trailing slash and add an explicit <c>/</c>
+when joining paths. For example: <c>${D%/}/</c>, <c>${ED%/}/</c>,
+<c>${ROOT%/}/</c>, <c>${EROOT%/}/</c>.
+</note>
+
+</body>
+</section>
+
 </chapter>
 </guide>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     9663bc625de09bf50c6605a856dff9e7c7cb9d2a
Author:     Wim Muskee <wimmuskee <AT> gmail <DOT> com>
AuthorDate: Sun Nov 13 14:59:54 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Nov 17 05:22:53 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9663bc62

ebuild-writing/variables: add explanation for no homepage to HOMEPAGE

 ebuild-writing/variables/text.xml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index f402070..7613b57 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -168,8 +168,10 @@ The following variables may or must be defined by every ebuild.
     Package's homepage. Mandatory (except for virtuals). If you are
     unable to locate an official one, try to provide a link to
     <uri link="http://freshmeat.net">freshmeat.net</uri> or a similar
-    package tracking site. Never refer to a variable name in the
-    string; include only raw text.
+    package tracking site. If the homepage of the package is unavailable
+    and no new location can be found, please update it to
+    <c>https://wiki.gentoo.org/wiki/No_homepage</c>.
+    Never refer to a variable name in the string; include only raw text.
     </ti>
   </tr>
   <tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     455267068a4c8274bdf66370949f7e349413d3c9
Author:     Wim Muskee <wimmuskee <AT> gmail <DOT> com>
AuthorDate: Wed Dec  7 19:41:21 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Dec  7 19:41:21 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=45526706

ebuild-writing/variable: document HTML_DOCS #591476

 ebuild-writing/variables/text.xml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 7613b57..e142e77 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -276,6 +276,15 @@ The following variables may or must be defined by every ebuild.
     <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.)
     </ti>
   </tr>
+  <tr>
+    <ti><c>HTML_DOCS</c></ti>
+    <ti>
+    An array or space-delimited list of documentation files or
+    directories for the <c>einstalldocs</c> function to install
+    recursively. (Requires
+    <uri link="::ebuild-writing/eapi/#eapi=6">EAPI>=6</uri>.)
+    </ti>
+  </tr>
 </table>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     f3e6cc0cb0113555bc6d9a622a9be3b9913f1a77
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Aug  7 17:28:23 2017 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Sat Sep  9 03:06:41 2017 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f3e6cc0c

ebuild-writing/variables: Discourage excessive use of constant-value variables

 ebuild-writing/variables/text.xml | 48 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index e142e77..6a6bbe8 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -588,5 +588,53 @@ when joining paths. For example: <c>${D%/}/</c>, <c>${ED%/}/</c>,
 </body>
 </section>
 
+<section>
+<title>Use of constant-value variables in ebuilds</title>
+<body>
+
+<p>
+Variables have significant value in ebuilds, making it possible to avoid
+unnecessary repetitions and make maintenance easier.  However,
+references to constant-value variables should be used with care as their
+excessive use can harm readability and increase maintenance burden (e.g.
+when renaming a package). In particular, using variables whose values
+have no direct correlation with the expected string should be avoided.
+</p>
+
+<p>The examples of beneficial constant-value variable references are:</p>
+<ul>
+  <li>
+    using <c>${PV}</c> and the variables derived from it (<c>${P}</c>,
+    <c>${MY_P}</c>…) in <c>SRC_URI</c> and <c>S</c> to avoid having
+    to update those variables for every version bump (assuming that
+    <c>${PV}</c> is used to indicate the upstream version);
+  </li>
+
+  <li>
+    using <c>${PF}</c> in <c>--docdir</c> path — this is a canonical
+    Gentoo path that is always required to match <c>${PF}</c>.
+  </li>
+</ul>
+
+<p>The examples of bad constant-value variable references are:</p>
+<ul>
+  <li>
+    using <c>${PN}</c> in <c>HOMEPAGE</c>, <c>EGIT_REPO_URI</c>
+    or the domain of <c>SRC_URI</c> — it breaks URL parsing in editors
+    and terminals, and makes it hard to copy the link for external use
+    (e.g. while reviewing via gitweb),
+  </li>
+
+  <li>
+    using <c>${PN}</c> (or other unnecessary helper variables)
+    excessively in <c>src_install()</c> — it impairs readability for
+    little benefit and causes a lot of trouble when the package needs to
+    be renamed.
+  </li>
+</ul>
+
+</body>
+</section>
+
 </chapter>
 </guide>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     714188ffeb0ee2ec92758a9eadb465616aea5afe
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Nov 12 20:11:10 2017 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Nov 12 20:11:10 2017 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=714188ff

ebuild-writing/variables: Fix a typo.

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 3a14b1c..5c800ad 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -577,7 +577,7 @@ need to suffix them with <c>/</c> when joining paths.
 
 <note>
 Future EAPI may remove the trailing slash at the end per
-<uri link="https://bugs.gentoo.org/465772">Bug 465722</uri>.
+<uri link="https://bugs.gentoo.org/465772">Bug 465772</uri>.
 To ease the transition, and ensure maximum compatibility with both the
 current and the future EAPI, developers are encouraged to use the bash
 suffix removal for the trailing slash and add an explicit <c>/</c>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Brian Evans]

commit:     f7b0e2c7b3fae81bcbfb69f16be8942be3564880
Author:     Brian Evans <grknight <AT> gentoo <DOT> org>
AuthorDate: Fri Sep 14 19:02:19 2018 +0000
Commit:     Brian Evans <grknight <AT> gentoo <DOT> org>
CommitDate: Wed Oct 24 12:56:35 2018 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f7b0e2c7

variables: Prefer eapi7-ver functions to versionator

Signed-off-by: Brian Evans <grknight <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 4829ea8..39aeb76 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -483,14 +483,18 @@ conventions. Using capital letters in names or differences in how underscores an
 are used in versions are particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be
 expecting a tarball named <c>Foo-1.2-3b.tar.bz2</c>. Rather than hard coding the package string,
 it is preferable to make <c>MY_PN</c>, <c>MY_PV</c> and <c>MY_P</c> variables and use those to define the
-upstream naming. The easy way of redefining the version, which should be used unless you are sure
-you know what you are doing, is to use the <c>versionator</c> eclass:
+upstream naming.
+EAPI=7 debuted a new set of functions, ver_cut, ver_rs and ver_test.
+These were backported into older EAPIs with the <c>eapi7-ver</c> eclass.
+The easy way of redefining the version, which should be used unless you are sure
+you know what you are doing, is to use these functions:
 </p>
 
 <codesample lang="ebuild">
-inherit versionator
+inherit eapi7-ver
 MY_PN="Foo"
-MY_PV=$(replace_version_separator 2 '-')
+# Replace the second period separator in PV with -
+MY_PV=$(ver_rs 2 '-')
 MY_P="${MY_PN}-${MY_PV}"
 </codesample>
 
@@ -501,7 +505,7 @@ switches to a format like <c>Foo-1.3-4.5.tar.bz2</c> (yes, this really happens).
 
 <p>
 It is also possible to use bash substitution to achieve the same effect (this is
-how versionator works internally), but this is complicated, error prone and hard
+how eapi7-ver works internally), but this is complicated, error prone and hard
 to read.
 </p>
 
@@ -513,8 +517,8 @@ highly discouraged.
 </p>
 
 <p>
-The <c>versionator</c> eclass can also be used to extract particular components
-from a version string. See <c>man versionator.eclass</c> and the eclass source code
+The ver_ functions are used extract particular components
+from a version string. See <c>man eapi7-ver.eclass</c> and the eclass source code
 for further documentation and examples. A brief summary of the functions
 follows.
 </p>
@@ -525,39 +529,35 @@ follows.
     <th>Purpose</th>
   </tr>
   <tr>
-    <ti><c>get_all_version_components</c></ti>
-    <ti>Split up a version string into its component parts.</ti>
-  </tr>
-  <tr>
-    <ti><c>get_version_components</c></ti>
+    <ti><c>ver_rs [range] ' '</c></ti>
     <ti>Get important version components, excluding '.', '-' and '_'.</ti>
   </tr>
   <tr>
-    <ti><c>get_major_version</c></ti>
+    <ti><c>ver_cut 1</c></ti>
     <ti>Get the major version.</ti>
   </tr>
   <tr>
-    <ti><c>get_version_component_range</c></ti>
+    <ti><c>ver_cut [range]</c></ti>
     <ti>Extract a range of subparts from a version string.</ti>
   </tr>
   <tr>
-    <ti><c>get_after_major_version</c></ti>
+    <ti><c>ver_cut 2-</c></ti>
     <ti>Get everything after the major version.</ti>
   </tr>
   <tr>
-    <ti><c>replace_version_separator</c></ti>
+    <ti><c>ver_rs [range] [char]</c></ti>
     <ti>Replace a particular version separator.</ti>
   </tr>
   <tr>
-    <ti><c>replace_all_version_separators</c></ti>
+    <ti><c>ver_rs 1- [char]</c></ti>
     <ti>Replace all version separators.</ti>
   </tr>
   <tr>
-    <ti><c>delete_version_separator</c></ti>
+    <ti><c>ver_rs [range] ''</c></ti>
     <ti>Delete a version separator.</ti>
   </tr>
   <tr>
-    <ti><c>delete_all_version_separators</c></ti>
+    <ti><c>ver_rs 1- ''</c></ti>
     <ti>Delete all version separators.</ti>
   </tr>
 </table>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Brian Evans]

commit:     273d8d7ba3cd6df5662628fd45ffc13ef214ba77
Author:     Brian Evans <grknight <AT> gentoo <DOT> org>
AuthorDate: Mon Sep 17 14:50:04 2018 +0000
Commit:     Brian Evans <grknight <AT> gentoo <DOT> org>
CommitDate: Wed Oct 24 12:56:36 2018 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=273d8d7b

ebuild-writing/variables: Add EAPI=7 variables

Signed-off-by: Brian Evans <grknight <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 811d92a..4cf24dc 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -128,7 +128,27 @@ for these variables when writing ebuilds.
   <tr>
     <ti><c>EROOT</c></ti>
     <ti>
-      Shorthand for <c>${ROOT%/}${EPREFIX}/</c>.
+      </c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>SYSROOT</c></ti>
+    <ti>
+      (EAPI=7) The absolute path to the root directory containing build dependencies
+		satisfied by <c>DEPEND</c>
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>ESYSROOT</c></ti>
+    <ti>
+      (EAPI=7) Shorthand for <c>${SYSROOT%/}${EPREFIX}/</c>.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>BROOT</c></ti>
+    <ti>
+      (EAPI=7) The absolute path to the root directory containing build dependencies
+		satisfied by <c>BDEPEND</c>, typically executable build tools.
     </ti>
   </tr>
 </table>
@@ -233,6 +253,14 @@ The following variables may or must be defined by every ebuild.
     <ti>
     A list of the package's build dependencies.  See
     <uri link="::general-concepts/dependencies"/>.
+    Starting with EAPI-7, applies to CHOST only.
+    </ti>
+  </tr>
+  <tr>
+    <ti><c>DEPEND</c></ti>
+    <ti>
+    (EAPI=7) A list of the package's CBUILD build dependencies.  See
+    <uri link="::general-concepts/dependencies"/>.
     </ti>
   </tr>
   <tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Brian Evans]

commit:     e4a6e552a4b2386893fca4d2834e0a38f89a5802
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Mon Nov  6 13:08:11 2017 +0000
Commit:     Brian Evans <grknight <AT> gentoo <DOT> org>
CommitDate: Tue Mar 19 17:02:04 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e4a6e552

ebuild-writing/variables: weaken the warning against third-party mirrors.

The warning against using third-party mirrors used to say that "the
mere existence of a third-party mirror list is not a good enough
reason to use it." That goes against a few existing uses of the
feature in the ::gentoo repository, so the wording is too strong. This
revision changes the warning, leaving the decision up to the
maintainer after alerting him to the potential maintenance burden.

Closes: https://bugs.gentoo.org/635646
Suggested-by: Michael Palimaka <kensington <AT> gentoo.org>
Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Brian Evans <grknight <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index d3255bd..4e4c76c 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -448,13 +448,15 @@ example http://download.example.org/ ftp://ftp.example.org/
 SRC_URI="mirror://example/${PN}/${P}.tar.gz"
 </codesample>
     <warning>
-      If the sources for a package are not mirror-restricted or
-      fetch-restricted, then there is little benefit to using this
-      feature: the sources will be <uri
+      If the sources for a package are neither mirror-restricted nor
+      fetch-restricted, then they will be <uri
       link="::general-concepts/mirrors">mirrored onto Gentoo
-      infrastructure</uri> anyway. In other words, the mere existence
-      of a third-party mirror list is not a good enough reason to use
-      it.
+      infrastructure</uri> automatically; in that case, there is
+      little benefit to using this feature. There is a maintenance
+      burden associated with using a third-party mirror list: it must
+      be updated when new mirrors are born and when old mirrors
+      die. Please consider that when deciding whether or not to use
+      this feature.
     </warning>
   </body>
 </subsection>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Brian Evans]

commit:     6ecbc55422bfd78865e16f077672357b3b321b34
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 28 01:43:46 2017 +0000
Commit:     Brian Evans <grknight <AT> gentoo <DOT> org>
CommitDate: Tue Mar 19 17:02:04 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6ecbc554

ebuild-writing/variables: document the mirror:// pseudo-protocol.

The thirdpartymirrors file is covered by the PMS, but unless you know
where to look, it's not easy to figure out what "mirror://" does in
SRC_URI. This commit adds a mention of the file and protocol under the
"SRC_URI" heading on the "Variables" page.

Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Brian Evans <grknight <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 44 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 98babe4..d3255bd 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -414,6 +414,50 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
 
 </body>
 </subsection>
+
+
+<subsection>
+  <title>Third-party mirrors</title>
+  <body>
+    <p>
+      If the items in <c>SRC_URI</c> are available on multiple
+      third-party mirrors, then you don't have to list each mirror in
+      your ebuild. The <c>profiles/thirdpartymirrors</c> file in the
+      <c>::gentoo</c> repository contains named groups of mirrors,
+      accessible through the <c>mirror://</c> pseudo-protocol.
+    </p>
+    <p>
+      As of EAPI 7, the format of <uri
+      link="https://projects.gentoo.org/pms/7/pms.html#x1-340004.4.2">the
+      thirdpartymirrors file</uri> is described in section 4.4.2 of
+      the Package Manager Specification (PMS). One might define a set
+      of &quot;example&quot; mirrors,
+    </p>
+<!--
+  The following isn't ebuild code, but lang="ebuild" works, and no
+  other language choice would be accurate either.
+-->
+<codesample lang="ebuild">
+example http://download.example.org/ ftp://ftp.example.org/
+</codesample>
+    <p>
+      that can afterwards be referenced through a <c>mirror://</c>
+      URL:
+    </p>
+<codesample lang="ebuild">
+SRC_URI="mirror://example/${PN}/${P}.tar.gz"
+</codesample>
+    <warning>
+      If the sources for a package are not mirror-restricted or
+      fetch-restricted, then there is little benefit to using this
+      feature: the sources will be <uri
+      link="::general-concepts/mirrors">mirrored onto Gentoo
+      infrastructure</uri> anyway. In other words, the mere existence
+      of a third-party mirror list is not a good enough reason to use
+      it.
+    </warning>
+  </body>
+</subsection>
 </section>
 
 <section>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     1b5a0169ffb0774c0cd63c9527821f39534b9f93
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 24 16:44:09 2019 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Mar 24 16:44:09 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1b5a0169

ebuild-writing/variables: Move PROPERTIES to proper place.

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

 ebuild-writing/variables/text.xml | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 4e4c76c..e63c8ff 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -240,6 +240,13 @@ The following variables may or must be defined by every ebuild.
     See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>.
     </ti>
   </tr>
+  <tr>
+    <ti><c>PROPERTIES</c></ti>
+    <ti>
+    A space-delimited list of properties, with conditional syntax support.
+    <c>interactive</c> is the only valid value for now.
+    </ti>
+  </tr>
   <tr>
     <ti><c>RESTRICT</c></ti>
     <ti>
@@ -287,14 +294,6 @@ The following variables may or must be defined by every ebuild.
     value for this variable if it is the same as the default value.
     </ti>
   </tr>
-  <tr>
-    <ti><c>PROPERTIES</c></ti>
-    <ti>
-    A space-delimited list of properties, with conditional
-    syntax support. <c>interactive</c> is the only valid value
-    for now.
-    </ti>
-  </tr>
   <tr>
     <ti><c>DOCS</c></ti>
     <ti>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     059da2527181ec9173f2addf8ac9ec2ce0fd704d
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Jun 18 10:12:12 2018 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed May 22 19:38:56 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=059da252

ebuild-writing/variables: Stop encouraging empty USE_EXPAND hack

Remove the suggestion that 'no flags = all options'.  We certainly
aren't doing it these days, and the problem is better resolved with
defaulting USE_EXPAND and/or REQUIRED_USE these days.

 ebuild-writing/variables/text.xml | 17 -----------------
 1 file changed, 17 deletions(-)

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>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     805a777188d74099f87ff55cb63f15241c7b6d92
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Oct 16 20:00:33 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 20:04:10 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=805a7771

ebuild-writing/variables: remove redundant thirdpartymirrors sentence

An earlier paragraph already mentions that the format of the
thirdpartymirrors file defined in PMS. No need to repeat it.

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 288e806..6195614 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -414,9 +414,6 @@ pseudo-protocol.
 </p>
 
 <p>
-As of EAPI 7, the format of <uri
-link="https://projects.gentoo.org/pms/7/pms.html#x1-340004.4.2">the
-thirdpartymirrors file</uri> is described in section 4.4.2 of the Package
 One might define a set of &quot;example&quot;
 mirrors,
 </p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     2d715449b39dbecbd8b6f26f2222074823c3bd3b
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Oct 16 19:57:02 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:58:04 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2d715449

ebuild-writing/variables: mirror:// is a URI, not URL per PMS 4.4.2

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index c60a52b..288e806 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -430,7 +430,7 @@ example https://download.example.com https://mirror1.example.org/example
 </codesample>
 
 <p>
-that can afterwards be referenced through a <c>mirror://</c> URL:
+that can afterwards be referenced through a <c>mirror://</c> URI:
 </p>
 
 <codesample lang="ebuild">

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     e77a5f0602fe383b2c9a6b38297f6d2b72e0e87d
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Tue Oct 15 19:43:39 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:44 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e77a5f06

Apply suggestions from code review

Closes: https://github.com/gentoo/devmanual.gentoo.org/pull/110
Co-Authored-By: Gokturk Yuksek <gokturk <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index e65d811..d71f5aa 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -407,7 +407,7 @@ If the items in <c>SRC_URI</c> are available on multiple third-party mirrors,
 and the same set of mirrors is shared across multiple ebuilds, then you
 don't have to repeatedly list each of them in every ebuild.
 The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository
-contains named groups of mirrors, accessible through the <c>mirror://</c>
+contains named groups of mirrors, in the format specified by the Package Manager Specification (PMS), accessible through the <c>mirror://</c>
 pseudo-protocol.
 </p>
 
@@ -415,7 +415,7 @@ pseudo-protocol.
 As of EAPI 7, the format of <uri
 link="https://projects.gentoo.org/pms/7/pms.html#x1-340004.4.2">the
 thirdpartymirrors file</uri> is described in section 4.4.2 of the Package
-Manager Specification (PMS). One might define a set of &quot;example&quot;
+One might define a set of &quot;example&quot;
 mirrors,
 </p>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     616c87a367714ffcf9c0ffd9c77989a9dad7b0d4
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Wed Oct 16 19:55:24 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:57:51 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=616c87a3

ebuild-writing/variables: line wrap a paragraph

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index d71f5aa..c60a52b 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -407,7 +407,9 @@ If the items in <c>SRC_URI</c> are available on multiple third-party mirrors,
 and the same set of mirrors is shared across multiple ebuilds, then you
 don't have to repeatedly list each of them in every ebuild.
 The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository
-contains named groups of mirrors, in the format specified by the Package Manager Specification (PMS), accessible through the <c>mirror://</c>
+contains named groups of mirrors, in the format specified by the
+Package Manager Specification (PMS), accessible through the
+<c>mirror://</c>
 pseudo-protocol.
 </p>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     80e159f6256dbb505d656ddf2b0aca540dbf3b40
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Oct  6 08:18:16 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:24 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=80e159f6

ebuild-writing/variables: Indicate multiple ebuild usage in tpm

Make it clearer that thirdpartymirrors should be used when multiple
ebuilds use the same mirror set.  It makes little sense to use it
when you are listing multiple random download locations for a particular
file.

Acked-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 23e423c..73ad8cf 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -404,7 +404,8 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
 
 <p>
 If the items in <c>SRC_URI</c> are available on multiple third-party mirrors,
-then you don't have to list each mirror in your ebuild.
+and the same set of mirrors is shared across multiple ebuilds, then you
+don't have to repeatedly list each of them in every ebuild.
 The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository
 contains named groups of mirrors, accessible through the <c>mirror://</c>
 pseudo-protocol.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     2e5916797a8906cbd7fa8c488a4d93be2a220577
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Oct  6 08:06:49 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:05 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2e591679

ebuild-writing/variables: Update the thirdpartymirrors example

Use HTTPS in the example, drop terminating slashes to indicate that
they're optional and include an example with additional directory path.

Acked-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 811be44..a66adc7 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -420,7 +420,7 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
   other language choice would be accurate either.
 -->
 <codesample lang="ebuild">
-example http://download.example.org/ ftp://ftp.example.org/
+example https://download.example.com https://mirror1.example.org/example
 </codesample>
     <p>
       that can afterwards be referenced through a <c>mirror://</c>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     ec810986a9150209cb45f0bbeefb4b644f1b82b8
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Oct  6 08:28:15 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:33 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ec810986

ebuild-writing/variables: Expand on when not to use tpm

Reintegrate the warning not to use thirdpartymirrors into main text
flow.  Expand on valid use cases for using it, and word the case against
using it more strongly.

Acked-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 73ad8cf..e65d811 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -435,15 +435,28 @@ that can afterwards be referenced through a <c>mirror://</c> URL:
 SRC_URI="mirror://example/${PN}/${P}.tar.gz"
 </codesample>
 
-<warning>
-If the sources for a package are neither mirror-restricted nor
-fetch-restricted, then they will be <uri
-link="::general-concepts/mirrors">mirrored onto Gentoo infrastructure</uri>
-automatically; in that case, there is little benefit to using this feature.
-There is a maintenance burden associated with using a third-party mirror list:
-it must be updated when new mirrors are born and when old mirrors die. Please
-consider that when deciding whether or not to use this feature.
-</warning>
+<p>
+There are two valid cases for using <c>thirdpartymirrors</c>:
+</p>
+
+<ol>
+  <li>
+    providing multiple download locations for mirror- or fetch-restricted
+    packages,
+  </li>
+
+  <li>
+    dealing with upstreams that distribute their distfiles via a network
+    of mirrors without a primary download location or a bouncer service.
+  </li>
+</ol>
+
+<p>
+In any other case, the primary location must be used instead. The distfiles
+will be <uri link="::general-concepts/mirrors">mirrored onto Gentoo
+infrastructure</uri>; in that case, the benefit to using third-party mirror
+list does not outweigh the burden of maintaining it.
+</p>
 
 </body>
 </subsection>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     2ee6d48917ae4c7646248fd2ad4e071fa2bbe6cd
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Oct  6 08:11:57 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:13 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2ee6d489

ebuild-writing/variables: Reindent section on mirror://

No text changes, just reformatting to the currently used style.

Acked-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 68 +++++++++++++++++++++------------------
 1 file changed, 36 insertions(+), 32 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index a66adc7..23e423c 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -399,22 +399,25 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
 
 
 <subsection>
-  <title>Third-party mirrors</title>
-  <body>
-    <p>
-      If the items in <c>SRC_URI</c> are available on multiple
-      third-party mirrors, then you don't have to list each mirror in
-      your ebuild. The <c>profiles/thirdpartymirrors</c> file in the
-      <c>::gentoo</c> repository contains named groups of mirrors,
-      accessible through the <c>mirror://</c> pseudo-protocol.
-    </p>
-    <p>
-      As of EAPI 7, the format of <uri
-      link="https://projects.gentoo.org/pms/7/pms.html#x1-340004.4.2">the
-      thirdpartymirrors file</uri> is described in section 4.4.2 of
-      the Package Manager Specification (PMS). One might define a set
-      of &quot;example&quot; mirrors,
-    </p>
+<title>Third-party mirrors</title>
+<body>
+
+<p>
+If the items in <c>SRC_URI</c> are available on multiple third-party mirrors,
+then you don't have to list each mirror in your ebuild.
+The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository
+contains named groups of mirrors, accessible through the <c>mirror://</c>
+pseudo-protocol.
+</p>
+
+<p>
+As of EAPI 7, the format of <uri
+link="https://projects.gentoo.org/pms/7/pms.html#x1-340004.4.2">the
+thirdpartymirrors file</uri> is described in section 4.4.2 of the Package
+Manager Specification (PMS). One might define a set of &quot;example&quot;
+mirrors,
+</p>
+
 <!--
   The following isn't ebuild code, but lang="ebuild" works, and no
   other language choice would be accurate either.
@@ -422,25 +425,26 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"
 <codesample lang="ebuild">
 example https://download.example.com https://mirror1.example.org/example
 </codesample>
-    <p>
-      that can afterwards be referenced through a <c>mirror://</c>
-      URL:
-    </p>
+
+<p>
+that can afterwards be referenced through a <c>mirror://</c> URL:
+</p>
+
 <codesample lang="ebuild">
 SRC_URI="mirror://example/${PN}/${P}.tar.gz"
 </codesample>
-    <warning>
-      If the sources for a package are neither mirror-restricted nor
-      fetch-restricted, then they will be <uri
-      link="::general-concepts/mirrors">mirrored onto Gentoo
-      infrastructure</uri> automatically; in that case, there is
-      little benefit to using this feature. There is a maintenance
-      burden associated with using a third-party mirror list: it must
-      be updated when new mirrors are born and when old mirrors
-      die. Please consider that when deciding whether or not to use
-      this feature.
-    </warning>
-  </body>
+
+<warning>
+If the sources for a package are neither mirror-restricted nor
+fetch-restricted, then they will be <uri
+link="::general-concepts/mirrors">mirrored onto Gentoo infrastructure</uri>
+automatically; in that case, there is little benefit to using this feature.
+There is a maintenance burden associated with using a third-party mirror list:
+it must be updated when new mirrors are born and when old mirrors die. Please
+consider that when deciding whether or not to use this feature.
+</warning>
+
+</body>
 </subsection>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     49add11ae54e82cc38e51b2aaf22e06fedecb918
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Nov  3 07:52:07 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Nov 26 01:48:46 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=49add11a

ebuild-writing/variables: explicitly discourage HOMEPAGE in SRC_URI

Closes: https://github.com/gentoo/devmanual/pull/115
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 8854a3a..35dc8f2 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -699,6 +699,11 @@ have no direct correlation with the expected string should be avoided.
     (e.g. while reviewing via gitweb),
   </li>
 
+  <li>
+    using <c>${HOMEPAGE}</c> in <c>SRC_URI</c> — it breaks when homepage
+    changes or additional entry is added,
+  </li>
+
   <li>
     using <c>${PN}</c> (or other unnecessary helper variables)
     excessively in <c>src_install()</c> — it impairs readability for

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     a3c28fc6d6cb008904c4705ff42611cc2d56c88b
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Nov  3 07:43:44 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Nov 26 01:47:20 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a3c28fc6

ebuild-writing/variables: Indicate that HOMEPAGE is multi-valued

Indicate that HOMEPAGE can accept multiple values.  Expand freshmeat
fallback suggestion into the broader idea that package trackers can
be linked in addition to main HOMEPAGE (which is a common practice
e.g. for Python packages).  Simplify No_homepage suggestion to always
use it when there's no homepage, rather than when transitioning from old
homepage.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 6195614..8854a3a 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -185,11 +185,12 @@ The following variables may or must be defined by every ebuild.
   <tr>
     <ti><c>HOMEPAGE</c></ti>
     <ti>
-    Package's homepage. Mandatory (except for virtuals). If you are
-    unable to locate an official one, try to provide a link to
-    <uri link="http://freshmeat.net">freshmeat.net</uri> or a similar
-    package tracking site. If the homepage of the package is unavailable
-    and no new location can be found, please update it to
+    Package's homepage(s). Mandatory (except for virtuals), accepts
+    multiple values. In some contexts, it is customary to provide
+    package tracker and/or code hosting links besides the main homepage
+    (e.g. PyPI link for Python packages, GitHub link when code can't
+    easily be found on homepage) for convenience. If no homepage for
+    the package is available, please set it to
     <c>https://wiki.gentoo.org/wiki/No_homepage</c>.
     Never refer to a variable name in the string; include only raw text.
     </ti>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     dabb1f76df1fe26cdf1b79d235b4ee3f0a9464cb
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Thu Nov 28 18:28:59 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Nov 28 18:32:29 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dabb1f76

ebuild-writing/variables: update the paragraph about trailing slashes

The information dates back to pre-EAPI7 era and incorrectly states
that ROOT etc. always end with a trailing slash, which is incorrect
with EAPI7. Update the text to reflect both EAPI7 and pre-EAPI7
practices and suggest the bash suffix removal for pre-EAPI7 ebuilds to
ease transition.

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index ffd2597..b6c84f7 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -644,21 +644,16 @@ follows.
 <body>
 
 <p>
-The following variables always end in a trailing slash by default:
-<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Therefore, there is no
-need to suffix them with <c>/</c> when joining paths.
+The following variables never end with a trailing slash in EAPI 7:
+<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Conversely, in EAPIS
+preceeding EAPI 7, these variables are guaranteed to end with a
+trailing slash. When working with EAPIs prior to EAPI 7, developers
+are encouraged to use the bash suffix removal for the trailing slash
+and add an explicit <c>/</c> when joining paths. For example:
+<c>${D%/}/</c>, <c>${ED%/}/</c>, <c>${ROOT%/}/</c>,
+<c>${EROOT%/}/</c>.
 </p>
 
-<note>
-Future EAPI may remove the trailing slash at the end per
-<uri link="https://bugs.gentoo.org/465772">Bug 465772</uri>.
-To ease the transition, and ensure maximum compatibility with both the
-current and the future EAPI, developers are encouraged to use the bash
-suffix removal for the trailing slash and add an explicit <c>/</c>
-when joining paths. For example: <c>${D%/}/</c>, <c>${ED%/}/</c>,
-<c>${ROOT%/}/</c>, <c>${EROOT%/}/</c>.
-</note>
-
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Göktürk Yüksek]

commit:     22e517a342ebf782fdb39afb4c7da23f6a9b4413
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Thu Nov 28 15:10:46 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Nov 28 15:15:37 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=22e517a3

ebuild-writing/variables: fix the trailing slash in ROOT for EAPI7

Before EAPI7, ROOT was guaranteed to end with a trailing slash. EAPI7
reversed this. Add back trailing slashes to ROOT in the example.

Reported-by: Conrad Kostecki <conrad <AT> kostecki.com>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 35dc8f2..ffd2597 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -534,11 +534,11 @@ old and obsolete configuration file still exists:
 
 <codesample lang="ebuild">
 pkg_postinst() {
-	if [[ -e "${ROOT}etc/oldconfig" ]]; then
+	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
 		ewarn "You still have the obsolete config file "
-		ewarn "    ${ROOT}etc/oldconfig."
-		ewarn "Please migrate your settings to ${ROOT}etc/newconfig"
-		ewarn "and remove ${ROOT}etc/oldconfig."
+		ewarn "    ${ROOT}/etc/oldconfig."
+		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
+		ewarn "and remove ${ROOT}/etc/oldconfig."
 	fi
 }
 </codesample>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     d4b42a176a0fce82490f39cd16f0d88164653ff2
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Nov 29 09:27:26 2019 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Nov 29 09:27:26 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d4b42a17

ebuild-writing/variables: Typo.

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

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index b6c84f7..e50a19e 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -645,7 +645,7 @@ follows.
 
 <p>
 The following variables never end with a trailing slash in EAPI 7:
-<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Conversely, in EAPIS
+<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Conversely, in EAPIs
 preceeding EAPI 7, these variables are guaranteed to end with a
 trailing slash. When working with EAPIs prior to EAPI 7, developers
 are encouraged to use the bash suffix removal for the trailing slash

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     f18faa6e7cc6cddfbddd35fea7ca042e5f030087
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Mar 11 14:33:42 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Mar 11 14:37:46 2020 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f18faa6e

ebuild-writing/variables: Replace codesample by pre.

Also remove a comment (which says that the sample isn't ebuild code,
so why was codesample used for it, in the first place?).

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

 ebuild-writing/variables/text.xml | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 863330b..56966b3 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -451,13 +451,9 @@ pseudo-protocol.
 One might define a set of "example" mirrors,
 </p>
 
-<!--
-  The following isn't ebuild code, but lang="ebuild" works, and no
-  other language choice would be accurate either.
--->
-<codesample lang="ebuild">
+<pre>
 example https://download.example.com https://mirror1.example.org/example
-</codesample>
+</pre>
 
 <p>
 that can afterwards be referenced through a <c>mirror://</c> URI:

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     d9793d70892f5107f4a140e14dfec15997ef65cc
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Jul  2 19:48:52 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 26 19:05:36 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d9793d70

ebuild-writing/variables: add a "User environment" section.

Gentoo has always tried to respect a user's CFLAGS environment
variable, ensuring that it is passed to the underlying build
system. Likewise, CC and LDFLAGS are well-respected these days.

Recently, we have added some other variables to this list, like NM,
RANLIB, LD, and AS. The meanings of most of these are enshrined in
toolchain-funcs.eclass, but in order to properly support them, we must
document their intended use so that user's can set them to the correct
value and developers can inject them into the right spot in the
upstream build system. One motivating example package is PARI, whose
build system interprets the LD environment variable in a different way
than GNU librool interprets it. If a user sets LD to something
appropriate for libtool, the PARI build will fail, and conversely;
that is, without help from the ebuild.

This commit adds a new section to the ebuild-writing/variables page
documenting the origin and intended use of these variables within
Gentoo. This should ensure that users and Gentoo developers agree on
their meanings, and will guide ebuild development when a problematic
upstream build system is encountered.

Closes: https://bugs.gentoo.org/730610
Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>
[Remove URI for "as". Whitespace fixes.]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 163 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 2ba4c4b..e947b88 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -806,5 +806,168 @@ REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"
 </subsection>
 </section>
 
+<section>
+<title>User environment</title>
+<body>
+
+<p>
+The following variables may be set in the user's environment and should be
+respected by all ebuilds. The purpose of each variable within Gentoo is listed
+alongside an example of a valid value. Upstream usage may diverge, but ebuilds
+should ensure that these variables are interpreted consistently within Gentoo.
+The chosen meanings are inspired by a few real and de-facto standards:
+</p>
+
+<ul>
+  <li>
+    <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html">
+    The POSIX (2018) make specification</uri>
+  </li>
+  <li>
+    <uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html">
+    The GNU make (v4.3) implementation</uri>
+  </li>
+  <li>
+    <uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT">
+    The GNU libtool (v2.4.6) package</uri>
+  </li>
+</ul>
+
+<p>
+Many of these variables only have an effect if they are invoked directly.
+For example, your compiler driver is usually responsible for assembling object
+files rather than a direct call to <c>${AS}</c>. In that case, setting
+<c>ASFLAGS</c> will have no effect on the build process; instead, you would set
+something like <c>CFLAGS="-Wa,-alh,-L"</c> to tell the C compiler to pass those
+flags to the assembler. The <c>LDFLAGS</c> variable is the exception to this
+rule, as it is intended to be passed to the compiler driver rather than
+<c>${LD}</c>.
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+    <th>Origin</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <ti><c>AR</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/ar.html">
+      ar</uri>-compatible library archiver
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>x86_64-pc-linux-gnu-ar</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ARFLAGS</c></ti>
+    <ti>flags for <c>${AR}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-v</c></ti>
+  </tr>
+  <tr>
+    <ti><c>AS</c></ti>
+    <ti>as-compatible assembler</ti>
+    <ti>GNU make</ti>
+    <ti><c>x86_64-pc-linux-gnu-as</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ASFLAGS</c></ti>
+    <ti>flags for <c>${AS}</c></ti>
+    <ti>GNU make</ti>
+    <ti><c>--reduce-memory-overheads</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CC</c></ti>
+    <ti>C compiler driver (also usually used for linking)</ti>
+    <ti>POSIX make</ti>
+    <ti><c>clang-9</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CFLAGS</c></ti>
+    <ti>flags for <c>${CC}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-march=native</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CPPFLAGS</c></ti>
+    <ti>flags for the C preprocessor</ti>
+    <ti>GNU make</ti>
+    <ti><c>-D_GNU_SOURCE</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CXX</c></ti>
+    <ti>C++ compiler driver (also usually used for linking)</ti>
+    <ti>GNU make</ti>
+    <ti><c>clang++</c></ti>
+  </tr>
+  <tr>
+    <ti><c>CXXFLAGS</c></ti>
+    <ti>flags for <c>${CXX}</c></ti>
+    <ti>GNU make</ti>
+    <ti><c>-fvisibility=hidden</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LD</c></ti>
+    <ti>dynamic linker</ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-ld</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LDFLAGS</c></ti>
+    <ti>flags for the <e>compiler driver</e> to pass to its linker</ti>
+    <ti>POSIX make</ti>
+    <ti><c>-Wl,-O1 -Wl,--as-needed</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LEX</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/lex.html">
+      lex</uri>-compatible lexer
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>/usr/bin/flex</c></ti>
+  </tr>
+  <tr>
+    <ti><c>LFLAGS</c></ti>
+    <ti>flags for <c>${LEX}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>--8bit --posix-compat</c></ti>
+  </tr>
+  <tr>
+    <ti><c>NM</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nm.html">
+      nm</uri>-compatible symbol extractor
+    </ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-nm</c></ti>
+  </tr>
+  <tr>
+    <ti><c>RANLIB</c></ti>
+    <ti>archive index generator</ti>
+    <ti>GNU libtool</ti>
+    <ti><c>x86_64-pc-linux-gnu-ranlib</c></ti>
+  </tr>
+  <tr>
+    <ti><c>YACC</c></ti>
+    <ti>
+      <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html">
+      yacc</uri>-compatible compiler-compiler
+    </ti>
+    <ti>POSIX make</ti>
+    <ti><c>/usr/bin/bison</c></ti>
+  </tr>
+  <tr>
+    <ti><c>YFLAGS</c></ti>
+    <ti>flags for <c>${YACC}</c></ti>
+    <ti>POSIX make</ti>
+    <ti><c>-d</c></ti>
+  </tr>
+</table>
+
+</body>
+</section>
 </chapter>
 </guide>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     8c577f4919845c22f4a7c26d599e71355e49438f
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 04:14:28 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 07:20:40 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8c577f49

ebuild-writing/variables: emphasise avoiding PDEPEND

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

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 01b0a69..ed62185 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -313,7 +313,7 @@ The following variables may or must be defined by every ebuild.
     <ti><c>PDEPEND</c></ti>
     <ti>
     A list of packages to be installed (if possible) after the package
-    is merged. Use this only when <c>RDEPEND</c> would cause cyclic
+    is merged. Use this <e>only</e> when <c>RDEPEND</c> would cause cyclic
     dependencies. See <uri link="::general-concepts/dependencies"/>.
     </ti>
   </tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     5a1b6eea498d603d5cb324452b83d3914586332b
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 04:12:49 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 07:20:40 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5a1b6eea

ebuild-writing/variables: add blank line after inherit in example

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

 ebuild-writing/variables/text.xml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index e947b88..01b0a69 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -594,6 +594,7 @@ you know what you are doing, is to use these functions:
 
 <codesample lang="ebuild">
 inherit eapi7-ver
+
 MY_PN="Foo"
 # Replace the second period separator in PV with -
 MY_PV=$(ver_rs 2 '-')

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     206a502dbb146687f60b3cd171ac98aea6bfabe6
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 05:06:12 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 07:20:41 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=206a502d

ebuild-writing/variables: mention PMS for acceptable RESTRICT values

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

 ebuild-writing/variables/text.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index ed62185..55cc3bd 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -524,6 +524,24 @@ GLEP 23</uri> for details.
 </body>
 </section>
 
+<section>
+<title>RESTRICT</title>
+<body>
+
+<p>
+While Portage may recognise several different <c>RESTRICT</c> tokens, it is
+important that you do not rely on them existing. That is, you should ensure
+your ebuild does not fail if those tokens are not exposed or given a different
+name by another package manager. You can make use of Portage-provided
+<c>RESTRICT</c> tokens, but do not fail hard without them. See
+<uri link="https://projects.gentoo.org/pms/7/pms.html#x1-810008.2.8">
+PMS</uri> for the list of standardised <c>RESTRICT</c> tokens, or the above
+table.
+</p>
+
+</body>
+</section>
+
 <section>
 <title>ROOT</title>
 <body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     6ebc0bd95ef60031be8bdba999f19c0d137ce05e
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 05:12:56 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 07:20:41 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6ebc0bd9

ebuild-writing/variables: minor tweak to eapi7-ver reference

Signed-off-by: Sam James <sam <AT> gentoo.org>
[Avoid "EAPI 7+", as "+" is a legal character in an EAPI name.]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 55cc3bd..97561e0 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -631,10 +631,11 @@ to read.
 </p>
 
 <p>
-Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This
-must <e>not</e> be done for any new code, and should be fixed to use either
-eapi7-ver or bash substitution where possible. Global scope non-bash code is
-highly discouraged.
+Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this.
+This must <e>not</e> be done for any new code and should be fixed to use
+built-in version manipulation commands (for EAPI 7 or later), Bash substitution,
+or in older EAPIs before 7, <c>eapi7-ver</c>. Global scope non-Bash code is
+<e>strongly</e> discouraged.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     5adf9875ec49c3eb8bfd73af2c0c59666bdbc1bd
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 05:16:49 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Mar 30 07:20:42 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5adf9875

ebuild-writing/variables: add link to helpful guide for versionator migration

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

 ebuild-writing/variables/text.xml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 97561e0..6b5f072 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -684,6 +684,13 @@ follows.
   </tr>
 </table>
 
+<note>
+A helpful guide to the newer complements of the old <c>versionator.eclass</c>
+functions can be found
+<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-7.html#replacing-versionator-eclass-uses">
+here</uri>, courtesy of Gentoo developer mgorny.
+</note>
+
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     8f74266195bb7e2673b855e6f1f10b0a0f7e3a83
Author:     Florian Schmaus <flo <AT> geekplace <DOT> eu>
AuthorDate: Fri May 28 08:07:03 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri May 28 13:08:44 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8f742661

ebuild-writing/variables: PROPERTIES may also contain 'live' and 'test_network'

Signed-off-by: Florian Schmaus <flo <AT> geekplace.eu>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 6b5f072..e45794d 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -276,7 +276,7 @@ The following variables may or must be defined by every ebuild.
     <ti><c>PROPERTIES</c></ti>
     <ti>
     A space-delimited list of properties, with conditional syntax support.
-    <c>interactive</c> is the only valid value for now.
+    <c>interactive</c>, <c>live</c>, and <c>test_network</c> are valid values.
     </ti>
   </tr>
   <tr>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Matthew Smith]

commit:     aec6c83e31a883f9777198b45e8356660afb35d4
Author:     Matthew Smith <matthew <AT> gentoo <DOT> org>
AuthorDate: Tue Feb 15 20:11:08 2022 +0000
Commit:     Matthew Smith <matthew <AT> gentoo <DOT> org>
CommitDate: Wed Feb 16 18:02:16 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=aec6c83e

ebuild-writing/variables: Selectively lifting SRC_URI restrictions

Closes: https://github.com/gentoo/devmanual/pull/271
Signed-off-by: Matthew Smith <matthew <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 62 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index e45794d..41976b2 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -431,7 +431,6 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -&gt; ${P}.tar.gz"
 </body>
 </subsection>
 
-
 <subsection>
 <title>Third-party mirrors</title>
 <body>
@@ -486,6 +485,67 @@ infrastructure</uri>; in that case, the benefit to using third-party mirror
 list does not outweigh the burden of maintaining it.
 </p>
 
+</body>
+</subsection>
+
+
+<subsection>
+<title>Lifting restrictions</title>
+<body>
+
+<p>
+In EAPI 8, individual items in <c>SRC_URI</c> can be exempted from automatic
+mirroring and fetching restrictions (imposed by <c>RESTRICT="mirror"</c> and
+<c>RESTRICT="fetch"</c>) by prefixing the addresses with <c>mirror+</c> or
+<c>fetch+</c>.  For example, in the following ebuild,
+</p>
+
+<codesample lang="ebuild">
+EAPI="8"
+
+SRC_URI="${P}.tar.gz
+	mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz"
+
+RESTRICT="fetch"
+</codesample>
+
+<p>
+Portage will be prevented from trying to fetch <c>${P}.tar.gz</c> as expected,
+but the <c>${P}-patches.tar.gz</c> file will be mirrored and fetched by Portage
+without restriction.
+</p>
+
+<p>
+The following table shows the effects of the prefixes when <c>RESTRICT="mirror"</c> and <c>RESTRICT="fetch"</c> are set:
+</p>
+
+<table>
+<tr>
+  <th></th>
+  <th><e>(no prefix)</e></th>
+  <th><c>fetch+</c></th>
+  <th><c>mirror+</c></th>
+</tr>
+<tr>
+  <th><e>(no RESTRICT)</e></th>
+  <ti>fetch &amp; mirror</ti>
+  <ti>fetch &amp; mirror</ti>
+  <ti>fetch &amp; mirror</ti>
+</tr>
+<tr>
+  <th><c>RESTRICT="mirror"</c></th>
+  <ti>fetch only</ti>
+  <ti>fetch only</ti>
+  <ti>fetch &amp; mirror</ti>
+</tr>
+<tr>
+  <th><c>RESTRICT="fetch"</c></th>
+  <ti>unfetchable</ti>
+  <ti>fetch only</ti>
+  <ti>fetch &amp; mirror</ti>
+</tr>
+</table>
+
 </body>
 </subsection>
 </section>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     9d82f20f7c579ac558f1179af8d332f763862728
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Feb 16 18:42:28 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Feb 16 18:42:28 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9d82f20f

ebuild-writing/variables: Whitespace

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

 ebuild-writing/variables/text.xml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 41976b2..9b2db1f 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -488,7 +488,6 @@ list does not outweigh the burden of maintaining it.
 </body>
 </subsection>
 
-
 <subsection>
 <title>Lifting restrictions</title>
 <body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Sam James]

commit:     1c2f5ca517d0dfa40b81871060b6b17f0e9acdf1
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 22 23:29:48 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Fri Feb 18 18:19:15 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=1c2f5ca5

ebuild-writing/variables: link to package/slot move page in SLOT

Closes: https://bugs.gentoo.org/388685
Signed-off-by: Sam James <sam <AT> gentoo.org>

 ebuild-writing/variables/text.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 9b2db1f..f07832e 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -360,7 +360,8 @@ When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use
 </p>
 
 <p>
-See <uri link="::general-concepts/slotting/" /> for more information on this variable.
+See <uri link="::general-concepts/slotting/" /> for more information on this
+variable and see <uri link="::ebuild-maintenance/package-moves/" />.
 </p>
 
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     65170e5755b44601f725d6c04e25ec2af3d6aba6
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Aug 17 06:57:22 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Aug 17 06:57:22 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=65170e57

ebuild-writing/variables: Demote single variable sections to subsections

Reorder subsections to follow the ordering of the tables.

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

 ebuild-writing/variables/text.xml | 340 +++++++++++++++++++-------------------
 1 file changed, 170 insertions(+), 170 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index f07832e..4c7df4f 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -185,6 +185,57 @@ for these variables when writing ebuilds.
 </table>
 
 </body>
+
+<subsection>
+<title>ROOT</title>
+<body>
+
+<p>
+The idea behind <c>ROOT</c> is that one can build a system with
+<c>ROOT=/somewhere</c> and then chroot into it or tar up
+<c>/somewhere</c> as a system image. It is not designed to allow the
+user to run <c>/somewhere/usr/bin/foo</c>.
+</p>
+
+<p>
+Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It
+can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may
+be different when merging a binary package. For example, a binary
+package may be built with <c>ROOT=/</c> and then installed onto a
+system using <c>ROOT=/somewhere</c>.
+</p>
+
+<p>
+When building a package, <c>ROOT</c> should not be used to satisfy the
+required dependencies on libraries, headers files etc. Instead, the
+files on the build system should be specified using <c>/</c>.
+</p>
+
+<p>
+In a cross compiling environment, ebuilds must not call any of the
+binaries inside <c>ROOT</c> since they may not be executable on the
+build system.
+</p>
+
+<p>
+Below is an example of an ebuild that uses <c>ROOT</c> in
+<c>pkg_postinst()</c> to conditionally print an error message if an
+old and obsolete configuration file still exists:
+</p>
+
+<codesample lang="ebuild">
+pkg_postinst() {
+	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
+		ewarn "You still have the obsolete config file "
+		ewarn "    ${ROOT}/etc/oldconfig."
+		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
+		ewarn "and remove ${ROOT}/etc/oldconfig."
+	fi
+}
+</codesample>
+
+</body>
+</subsection>
 </section>
 
 <section>
@@ -348,45 +399,11 @@ The following variables may or must be defined by every ebuild.
 </table>
 
 </body>
-</section>
 
-<section>
-<title>SLOT</title>
-<body>
-
-<p>
-When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use
-<c>SLOT=""</c>, because the variable must not be empty.
-</p>
-
-<p>
-See <uri link="::general-concepts/slotting/" /> for more information on this
-variable and see <uri link="::ebuild-maintenance/package-moves/" />.
-</p>
-
-</body>
-</section>
-
-<section>
-<title>KEYWORDS</title>
-<body>
-
-<p>
-The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do
-<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>.
-</p>
-
-<p>
-See <uri link="::keywording/"/> for how to handle this variable.
-</p>
-
-</body>
-</section>
-
-<section>
+<subsection>
 <title>SRC_URI</title>
 
-<subsection>
+<subsubsection>
 <title>Conditional Sources</title>
 <body>
 
@@ -405,9 +422,9 @@ SRC_URI="https://example.com/files/${P}-core.tar.bz2
 </codesample>
 
 </body>
-</subsection>
+</subsubsection>
 
-<subsection>
+<subsubsection>
 <title>Renaming Sources</title>
 <body>
 
@@ -430,9 +447,9 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -&gt; ${P}.tar.gz"
 </codesample>
 
 </body>
-</subsection>
+</subsubsection>
 
-<subsection>
+<subsubsection>
 <title>Third-party mirrors</title>
 <body>
 
@@ -487,9 +504,9 @@ list does not outweigh the burden of maintaining it.
 </p>
 
 </body>
-</subsection>
+</subsubsection>
 
-<subsection>
+<subsubsection>
 <title>Lifting restrictions</title>
 <body>
 
@@ -547,110 +564,161 @@ The following table shows the effects of the prefixes when <c>RESTRICT="mirror"<
 </table>
 
 </body>
+</subsubsection>
 </subsection>
-</section>
 
-<section>
-<title>IUSE</title>
+<subsection>
+<title>LICENSE</title>
 <body>
 
 <p>
-Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
-USE flags used only within inherited eclasses within the ebuild's IUSE.
-</p>
-<note>
-You need not assign the IUSE variable in your ebuild if it is empty.
-</note>
-
-<p>
-Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x64-macos</c> and so on) should
-not be listed.
+It is possible to specify multiple <c>LICENSE</c> entries, and entries which only
+apply if a particular <c>USE</c> flag is set. The format is the same as for
+<c>DEPEND</c>. See <uri link="https://www.gentoo.org/glep/glep-0023.html">
+GLEP 23</uri> for details.
 </p>
 
 </body>
-</section>
+</subsection>
 
-<section>
-<title>LICENSE</title>
+<subsection>
+<title>SLOT</title>
 <body>
 
 <p>
-It is possible to specify multiple <c>LICENSE</c> entries, and entries which only
-apply if a particular <c>USE</c> flag is set. The format is the same as for
-<c>DEPEND</c>. See <uri link="https://www.gentoo.org/glep/glep-0023.html">
-GLEP 23</uri> for details.
+When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use
+<c>SLOT=""</c>, because the variable must not be empty.
+</p>
+
+<p>
+See <uri link="::general-concepts/slotting/" /> for more information on this
+variable and see <uri link="::ebuild-maintenance/package-moves/" />.
 </p>
 
 </body>
-</section>
+</subsection>
 
-<section>
-<title>RESTRICT</title>
+<subsection>
+<title>KEYWORDS</title>
 <body>
 
 <p>
-While Portage may recognise several different <c>RESTRICT</c> tokens, it is
-important that you do not rely on them existing. That is, you should ensure
-your ebuild does not fail if those tokens are not exposed or given a different
-name by another package manager. You can make use of Portage-provided
-<c>RESTRICT</c> tokens, but do not fail hard without them. See
-<uri link="https://projects.gentoo.org/pms/7/pms.html#x1-810008.2.8">
-PMS</uri> for the list of standardised <c>RESTRICT</c> tokens, or the above
-table.
+The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do
+<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>.
+</p>
+
+<p>
+See <uri link="::keywording/"/> for how to handle this variable.
 </p>
 
 </body>
-</section>
+</subsection>
 
-<section>
-<title>ROOT</title>
+<subsection>
+<title>IUSE</title>
 <body>
 
 <p>
-The idea behind <c>ROOT</c> is that one can build a system with
-<c>ROOT=/somewhere</c> and then chroot into it or tar up
-<c>/somewhere</c> as a system image. It is not designed to allow the
-user to run <c>/somewhere/usr/bin/foo</c>.
+Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
+USE flags used only within inherited eclasses within the ebuild's IUSE.
 </p>
+<note>
+You need not assign the IUSE variable in your ebuild if it is empty.
+</note>
 
 <p>
-Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It
-can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may
-be different when merging a binary package. For example, a binary
-package may be built with <c>ROOT=/</c> and then installed onto a
-system using <c>ROOT=/somewhere</c>.
+Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x64-macos</c> and so on) should
+not be listed.
 </p>
 
+</body>
+</subsection>
+
+<subsection>
+<title>REQUIRED_USE</title>
+<body>
 <p>
-When building a package, <c>ROOT</c> should not be used to satisfy the
-required dependencies on libraries, headers files etc. Instead, the
-files on the build system should be specified using <c>/</c>.
+The <c>REQUIRED_USE</c> variable contains a list of assertions that must be
+met by the configuration of USE flags to be valid for this ebuild. In order
+to be matched, a USE flag in a terminal element must be enabled
+(or disabled if it has an exclamation mark prefix).
 </p>
 
 <p>
-In a cross compiling environment, ebuilds must not call any of the
-binaries inside <c>ROOT</c> since they may not be executable on the
-build system.
+Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax.
+For example, to state that some combination is forbidden, i.e. "if foo is set,
+bar must be unset":
 </p>
 
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( !bar )"
+</codesample>
 <p>
-Below is an example of an ebuild that uses <c>ROOT</c> in
-<c>pkg_postinst()</c> to conditionally print an error message if an
-old and obsolete configuration file still exists:
+To state "if foo is set, then at least one of bar, baz, and quux must be activated":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( || ( bar baz quux ) )"
+</codesample>
+<p>
+To state "exactly one of foo, bar, or baz must be set, but not several":
 </p>
+<codesample lang="ebuild">
+REQUIRED_USE="^^ ( foo bar baz )"
+</codesample>
+<p>
+Note that the last relationship is that of an Exclusive OR (XOR).
+While an XOR could be formed from usual DEPEND syntax,
+a specific ^^ operator has been added for this case.
+</p>
+<p>
+Finally, to state "at least one of foo, bar, or baz must be set":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="|| ( foo bar baz )"
+</codesample>
+<important>
+See section <uri link="::general-concepts/use-flags/#Conflicting USE Flags"/>
+for when (and when not) to use <c>REQUIRED_USE</c>.
+</important>
+</body>
 
+<subsubsection>
+<title>EAPI 5</title>
+<body>
+<p>
+EAPI 5 added an additional case to simplify conflicting USE flags.
+</p>
+<p>
+To state "zero or one of foo, bar, or baz must be set, but not several":
+</p>
 <codesample lang="ebuild">
-pkg_postinst() {
-	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
-		ewarn "You still have the obsolete config file "
-		ewarn "    ${ROOT}/etc/oldconfig."
-		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
-		ewarn "and remove ${ROOT}/etc/oldconfig."
-	fi
-}
+REQUIRED_USE="?? ( foo bar baz )"
+</codesample>
+<p>In the previous EAPI, this would be the same as:</p>
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"
 </codesample>
+</body>
+</subsubsection>
+</subsection>
+
+<subsection>
+<title>RESTRICT</title>
+<body>
+
+<p>
+While Portage may recognise several different <c>RESTRICT</c> tokens, it is
+important that you do not rely on them existing. That is, you should ensure
+your ebuild does not fail if those tokens are not exposed or given a different
+name by another package manager. You can make use of Portage-provided
+<c>RESTRICT</c> tokens, but do not fail hard without them. See
+<uri link="https://projects.gentoo.org/pms/7/pms.html#x1-810008.2.8">
+PMS</uri> for the list of standardised <c>RESTRICT</c> tokens, or the above
+table.
+</p>
 
 </body>
+</subsection>
 </section>
 
 <section>
@@ -825,74 +893,6 @@ have no direct correlation with the expected string should be avoided.
 </body>
 </section>
 
-<section>
-<title>REQUIRED_USE</title>
-<body>
-<p>
-The <c>REQUIRED_USE</c> variable contains a list of assertions that must be
-met by the configuration of USE flags to be valid for this ebuild. In order
-to be matched, a USE flag in a terminal element must be enabled
-(or disabled if it has an exclamation mark prefix).
-</p>
-
-<p>
-Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax.
-For example, to state that some combination is forbidden, i.e. "if foo is set,
-bar must be unset":
-</p>
-
-<codesample lang="ebuild">
-REQUIRED_USE="foo? ( !bar )"
-</codesample>
-<p>
-To state "if foo is set, then at least one of bar, baz, and quux must be activated":
-</p>
-<codesample lang="ebuild">
-REQUIRED_USE="foo? ( || ( bar baz quux ) )"
-</codesample>
-<p>
-To state "exactly one of foo, bar, or baz must be set, but not several":
-</p>
-<codesample lang="ebuild">
-REQUIRED_USE="^^ ( foo bar baz )"
-</codesample>
-<p>
-Note that the last relationship is that of an Exclusive OR (XOR).
-While an XOR could be formed from usual DEPEND syntax,
-a specific ^^ operator has been added for this case.
-</p>
-<p>
-Finally, to state "at least one of foo, bar, or baz must be set":
-</p>
-<codesample lang="ebuild">
-REQUIRED_USE="|| ( foo bar baz )"
-</codesample>
-<important>
-See section <uri link="::general-concepts/use-flags/#Conflicting USE Flags"/>
-for when (and when not) to use <c>REQUIRED_USE</c>.
-</important>
-</body>
-
-<subsection>
-<title>EAPI 5</title>
-<body>
-<p>
-EAPI 5 added an additional case to simplify conflicting USE flags.
-</p>
-<p>
-To state "zero or one of foo, bar, or baz must be set, but not several":
-</p>
-<codesample lang="ebuild">
-REQUIRED_USE="?? ( foo bar baz )"
-</codesample>
-<p>In the previous EAPI, this would be the same as:</p>
-<codesample lang="ebuild">
-REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"
-</codesample>
-</body>
-</subsection>
-</section>
-
 <section>
 <title>User environment</title>
 <body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     7ef569e7b5487784b5cab81daef60cd920da2082
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Aug 17 07:08:26 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Aug 18 16:02:10 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7ef569e7

ebuild-writing/variables: Add section about reserved variables

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

 ebuild-writing/variables/text.xml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index 4c7df4f..d77f4b7 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -721,6 +721,41 @@ table.
 </subsection>
 </section>
 
+<section>
+<title>Variables reserved for the package manager</title>
+<body>
+
+<p>
+Variables and functions that begin with any of the following strings (ignoring
+case) are reserved for package manager use. Ebuilds must neither use them nor
+rely upon them:
+</p>
+
+<ul>
+  <li><c>__</c> (two underscores)</li>
+  <li><c>abort</c></li>
+  <li><c>dyn</c></li>
+  <li><c>prep</c></li>
+</ul>
+
+<p>
+The same applies to functions and variables that contain any of the following
+strings (ignoring case):
+</p>
+
+<ul>
+  <li>
+    <c>ebuild</c> (unless immediately preceded by another letter, and except
+    for the <c>EBUILD_PHASE</c> and <c>EBUILD_PHASE_FUNC</c> variables)
+  </li>
+  <li><c>hook</c></li>
+  <li><c>paludis</c></li>
+  <li><c>portage</c></li>
+</ul>
+
+</body>
+</section>
+
 <section>
 <title>Version and Name Formatting Issues</title>
 <body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/variables/

[Ulrich Müller]

commit:     f73fcfb9352f815d44a0198516ac759caa6e09ec
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Aug 18 07:45:05 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Aug 25 16:41:07 2022 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f73fcfb9

ebuild-writing/variables: Fix example for ROOT

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

 ebuild-writing/variables/text.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
index d77f4b7..03d8752 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -225,8 +225,8 @@ old and obsolete configuration file still exists:
 
 <codesample lang="ebuild">
 pkg_postinst() {
-	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
-		ewarn "You still have the obsolete config file "
+	if [[ -e ${ROOT}/etc/oldconfig ]]; then
+		ewarn "You still have the obsolete config file"
 		ewarn "    ${ROOT}/etc/oldconfig."
 		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
 		ewarn "and remove ${ROOT}/etc/oldconfig."