diff options
authorMichał Górny <>2020-01-09 16:43:37 +0100
committerMichał Górny <>2020-01-09 16:44:09 +0100
commit29ad3c8d1ad986a019e8d06478f95f9c4c412c90 (patch)
parentEbuild coding style (diff)
Signed-off-by: Michał Górny <>
1 files changed, 39 insertions, 0 deletions
diff --git a/ebuild-format.rst b/ebuild-format.rst
index 9f78705..d2c8dc5 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -48,3 +48,42 @@ converted into eclasses.
the principle of least surprise. It makes the maintenance harder,
confuses other developers and tools that do not explicitly account for
that possibility, including linting tools.
+.. index:: homepage; variable
+HOMEPAGE must not contain variables
+:Source: QA
+:Reported: by pkgcheck, highlighted as error by gentoo-syntax
+The ``HOMEPAGE`` variable in ebuild must specify all the URIs verbatim,
+without referring to any variables. Variable references are allowed
+when setting generic values in eclasses.
+*Rationale*: since homepage URIs do not contain dynamic parts (such
+as package versions), there is little advantage to using variables
+there. On the other hand, variables render the URIs unusable without
+preprocessing, breaking URI support in terminals and editors, as well
+as reducing the usefulness of plain tools such as grep.
+.. index::
+ pair: src uri; homepage
+SRC_URI must not refer to HOMEPAGE
+:Source: QA
+:Reported: by pkgcheck
+The ``SRC_URI`` variable in ebuild must not refer to ``${HOMEPAGE}``.
+If both overlap, the common part must be repeated verbatim.
+*Rationale*: ``HOMEPAGE`` permits multiple entries by design,
+and developers are generally encouraged to add more helpful entries
+(e.g. project pages on PyPI, GitHub...). Making individual URIs
+incidentally depend on multi-valued variable having a single value
+goes against the principle of least surprise. Furthermore, it makes
+it hard to copy-paste part of the URI e.g. to investigate the directory