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 "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"> +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>
