@@ -1416,6 +1416,58 @@ overview of their function and contents.
upstream source, and then locations specified by :term:`MIRRORS` in that
order.
+ This variable has a specific syntax. Each line must contain a regular
+ expression matching the original source URL and a replacement URL for it.
+ For example::
+
+ MIRRORS:prepend = " \
+ git://git.openembedded.org/.* git:///mirrors/openembedded/BASENAME \
+ "
+
+ In the above example:
+
+ - The leftmost part means that any Git repository (``git://`` fetcher)
+ whose URL starts with ``git.openembedded.org/`` will be matched.
+
+ - The rightmost part is the replacement URL for the original repository,
+ which is hosted locally in the ``/mirrors/openembedded`` directory. It
+ also uses the ``BASENAME`` keyword which is detailed below.
+
+ The rightmost part of each line can contain keywords which are
+ automatically replaced by BitBake. These keywords can contain either a
+ sub-part of the original URL or meta-information about it.
+
+ For what follows, let's take the following URL as an example for the
+ original source (matched by the leftmost part of the line):
+ ``git://git.openembedded.org/project/repo.git``.
+
+ A replacement for this URL can be created using the following keywords:
+
+ - ``TYPE``: the URL scheme or fetcher type. For the example above: ``git``.
+ - ``HOST``: the URL host. For the example above: ``git.openembedded.org``.
+ - ``PATH``: the URL path. For the example above: ``/project/repo.git``.
+ - ``BASENAME``: the URL basename. For the example above: ``repo.git``.
+ - ``MIRRORNAME``: a translation of the host and path with common
+ characters substituted to dots (``.``). For the example above:
+ ``git.openembedded.org.project.repo.git``.
+
+ The rightmost part of the line can also be a bare URL that uses no special
+ keywords (usually ``https://`` or ``file://``). For example::
+
+ MIRRORS:prepend = " \
+ git://git.openembedded.org/.* file:///mirrors/openembedded/ \
+ "
+
+ In the above example, the fetcher will try to find a mirror tarball in the
+ ``/mirrors/openembedded`` directory. The name of this tarball should follow
+ the name of the tarball created by BitBake (for Git repositories,
+ the :term:`BB_GENERATE_MIRROR_TARBALLS` variable must be set to "1" to
+ generate them).
+
+ If we take ``git://git.openembedded.org/project/repo.git`` as an example,
+ the tarball would have to be named
+ ``git2_git.openembedded.org.project.repo.git.tar.gz``.
+
:term:`OVERRIDES`
A colon-separated list that BitBake uses to control what variables are
overridden after BitBake parses recipes and configuration files.
@@ -1544,6 +1596,10 @@ overview of their function and contents.
use ``file://`` URLs to point to local directories or network shares as
well.
+ The syntax of the :term:`PREMIRRORS` variable is the same as
+ :term:`MIRRORS`. See the definition of the :term:`MIRRORS` for more
+ details.
+
:term:`PROVIDES`
A list of aliases by which a particular recipe can be known. By
default, a recipe's own :term:`PN` is implicitly already in its
The MIRRORS variable wasn't properly documented as Ross highlighted in bug 16297. Give it a proper description detailing its usage and which keywords are available. Also link PREMIRRORS to MIRRORS as they use the same syntax. [YOCTO #16297] Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- Changes in v2: - Address comments by Quentin - Link to v1: https://patch.msgid.link/20260601-clarify-mirrors-syntax-v1-1-d9dbdbaf037f@bootlin.com To: bitbake-devel@lists.openembedded.org Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com> Cc: docs@lists.yoctoproject.org --- .../bitbake-user-manual-ref-variables.rst | 56 ++++++++++++++++++++++ 1 file changed, 56 insertions(+) --- base-commit: e74cfd03afe5aff1f81cbff8c6efcef77c9af618 change-id: 20260601-clarify-mirrors-syntax-e3abbf7c0e49