summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJonathan Maw <jonathan.maw@codethink.co.uk>2018-06-27 14:27:25 +0100
committerJonathan Maw <jonathan.maw@codethink.co.uk>2018-07-27 12:24:56 +0000
commit1cbc2e17f782d8765b33c092c42ebdd98510ae62 (patch)
tree1ae91499ae1f7da6b672c0325bd0bc076c44127a /doc
parent909120abc32fe3b132f71a13ea94b1f9f929c05c (diff)
downloadbuildstream-1cbc2e17f782d8765b33c092c42ebdd98510ae62.tar.gz
doc: Add documentation for source mirroring
Diffstat (limited to 'doc')
-rw-r--r--doc/source/format_project.rst37
-rw-r--r--doc/source/using_config.rst21
2 files changed, 58 insertions, 0 deletions
diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 36de41a55..cf0970f77 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -198,6 +198,43 @@ You can also specify a list of caches here; earlier entries in the list
will have higher priority than later ones.
+.. _project_essentials_mirrors:
+
+Mirrors
+~~~~~~~
+A list of mirrors can be defined that couple a location to a mapping of aliases to a
+list of URIs, e.g.
+
+.. code:: yaml
+
+ mirrors:
+ - name: middle-earth
+ aliases:
+ foo:
+ - http://www.middle-earth.com/foo/1
+ - http://www.middle-earth.com/foo/2
+ bar:
+ - http://www.middle-earth.com/bar/1
+ - http://www.middle-earth.com/bar/2
+ - name: oz
+ aliases:
+ foo:
+ - http://www.oz.com/foo
+ bar:
+ - http://www.oz.com/bar
+
+The order that the mirrors (and the URIs therein) are consulted is in the order
+they are defined when fetching, and in reverse-order when tracking.
+
+A default mirror to consult first can be defined via
+:ref:`user config <config_default_mirror>`, or the command-line argument
+:ref:`--default-mirror <invoking_bst>`.
+
+.. note::
+
+ The ``mirrors`` field is available since :ref:`format version 11 <project_format_version>`
+
+
.. _project_plugins:
External plugins
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
index d02aaf3d4..c707cd04b 100644
--- a/doc/source/using_config.rst
+++ b/doc/source/using_config.rst
@@ -89,6 +89,27 @@ modifying some low level component.
the ``--strict`` and ``--no-strict`` command line options.
+.. _config_default_mirror:
+
+Default Mirror
+~~~~~~~~~~~~~~
+When using :ref:`mirrors <project_essentials_mirrors>`, a default mirror can
+be defined to be fetched first.
+The default mirror is defined by its name, e.g.
+
+.. code:: yaml
+
+ projects:
+ project-name:
+ default-mirror: oz
+
+
+.. note::
+
+ It is possible to override this at invocation time using the
+ ``--default-mirror`` command-line option.
+
+
Default configuration
---------------------
The default BuildStream configuration is specified here for reference: