diff options
author | Michał Górny <mgorny@gentoo.org> | 2020-01-09 16:43:37 +0100 |
---|---|---|
committer | Michał Górny <mgorny@gentoo.org> | 2020-01-09 16:44:09 +0100 |
commit | 29ad3c8d1ad986a019e8d06478f95f9c4c412c90 (patch) | |
tree | 33dcd00f3e0d171e9d7e146bf7a24b5dd114d76c | |
parent | Ebuild coding style (diff) | |
download | policy-guide-29ad3c8d1ad986a019e8d06478f95f9c4c412c90.tar.gz policy-guide-29ad3c8d1ad986a019e8d06478f95f9c4c412c90.tar.bz2 policy-guide-29ad3c8d1ad986a019e8d06478f95f9c4c412c90.zip |
HOMEPAGE and SRC_URI format
Signed-off-by: Michał Górny <mgorny@gentoo.org>
-rw-r--r-- | ebuild-format.rst | 39 |
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 +index. |