| 1 |
commit: f3e6cc0cb0113555bc6d9a622a9be3b9913f1a77 |
| 2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Mon Aug 7 17:28:23 2017 +0000 |
| 4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Sat Sep 9 03:06:41 2017 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=f3e6cc0c |
| 7 |
|
| 8 |
ebuild-writing/variables: Discourage excessive use of constant-value variables |
| 9 |
|
| 10 |
ebuild-writing/variables/text.xml | 48 +++++++++++++++++++++++++++++++++++++++ |
| 11 |
1 file changed, 48 insertions(+) |
| 12 |
|
| 13 |
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml |
| 14 |
index e142e77..6a6bbe8 100644 |
| 15 |
--- a/ebuild-writing/variables/text.xml |
| 16 |
+++ b/ebuild-writing/variables/text.xml |
| 17 |
@@ -588,5 +588,53 @@ when joining paths. For example: <c>${D%/}/</c>, <c>${ED%/}/</c>, |
| 18 |
</body> |
| 19 |
</section> |
| 20 |
|
| 21 |
+<section> |
| 22 |
+<title>Use of constant-value variables in ebuilds</title> |
| 23 |
+<body> |
| 24 |
+ |
| 25 |
+<p> |
| 26 |
+Variables have significant value in ebuilds, making it possible to avoid |
| 27 |
+unnecessary repetitions and make maintenance easier. However, |
| 28 |
+references to constant-value variables should be used with care as their |
| 29 |
+excessive use can harm readability and increase maintenance burden (e.g. |
| 30 |
+when renaming a package). In particular, using variables whose values |
| 31 |
+have no direct correlation with the expected string should be avoided. |
| 32 |
+</p> |
| 33 |
+ |
| 34 |
+<p>The examples of beneficial constant-value variable references are:</p> |
| 35 |
+<ul> |
| 36 |
+ <li> |
| 37 |
+ using <c>${PV}</c> and the variables derived from it (<c>${P}</c>, |
| 38 |
+ <c>${MY_P}</c>…) in <c>SRC_URI</c> and <c>S</c> to avoid having |
| 39 |
+ to update those variables for every version bump (assuming that |
| 40 |
+ <c>${PV}</c> is used to indicate the upstream version); |
| 41 |
+ </li> |
| 42 |
+ |
| 43 |
+ <li> |
| 44 |
+ using <c>${PF}</c> in <c>--docdir</c> path — this is a canonical |
| 45 |
+ Gentoo path that is always required to match <c>${PF}</c>. |
| 46 |
+ </li> |
| 47 |
+</ul> |
| 48 |
+ |
| 49 |
+<p>The examples of bad constant-value variable references are:</p> |
| 50 |
+<ul> |
| 51 |
+ <li> |
| 52 |
+ using <c>${PN}</c> in <c>HOMEPAGE</c>, <c>EGIT_REPO_URI</c> |
| 53 |
+ or the domain of <c>SRC_URI</c> — it breaks URL parsing in editors |
| 54 |
+ and terminals, and makes it hard to copy the link for external use |
| 55 |
+ (e.g. while reviewing via gitweb), |
| 56 |
+ </li> |
| 57 |
+ |
| 58 |
+ <li> |
| 59 |
+ using <c>${PN}</c> (or other unnecessary helper variables) |
| 60 |
+ excessively in <c>src_install()</c> — it impairs readability for |
| 61 |
+ little benefit and causes a lot of trouble when the package needs to |
| 62 |
+ be renamed. |
| 63 |
+ </li> |
| 64 |
+</ul> |
| 65 |
+ |
| 66 |
+</body> |
| 67 |
+</section> |
| 68 |
+ |
| 69 |
</chapter> |
| 70 |
</guide> |
Archives