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>
