building: add section about building stable 3.1.0 to 3.8.0

Versions 3.1.0 to 3.8.0 are known to cause issues when cloning with a
version of the repo tool >= v2.0.0. Document this fact and provide a
workaround.

Signed-off-by: Jerome Forissier <jerome@forissier.org>
Acked-by: Etienne Carriere <etienne.carriere@linaro.org>
Acked-by: Jens Wiklander <jens.wiklander@linaro.org>

building/gits/build.rst

@@ -223,6 +223,12 @@ Before OP-TEE ``v3.1`` we used to have separate xml-manifest files for the
 stable builds. If you for some reason need an older stable release, please
 refer to ":ref:`build_legacy`".
 
+Stable releases prior to OP-TEE v3.9 (3.1.0 to 3.8.0)
+=====================================================
+Due to a change in the Google repo tool, you might get an error when cloning
+OP-TEE repositories before version ``3.9.0``. In this case please refer to
+":ref:`build_legacy_3_1_0-3_8_0`".
+
 .. _get_and_build_the_solution:
 
 

building/gits/build_legacy_3_1_0-3_8_0.rst

@@ -0,0 +1,31 @@
+.. _build_legacy_3_1_0-3_8_0:
+
+######################################
+Build stable releases 3.1.0 to 3.8.0
+######################################
+If you have a recent enough version of the Google repo tool (>= ``2.0.0``)
+and follow the normal build procedure at ":ref:`get_and_build_the_solution`",
+you will likely get an error during ``repo init`` with the following OP-TEE
+versions and platforms:
+
+    - 3.1.0 to 3.5.0: ``qemu_v8.xml``, ``rpi3.xml``
+    - 3.6.0 to 3.8.0: ``default.xml`` (QEMU), ``qemu_v8.xml``, ``rpi3.xml``
+
+The typical error message is:
+
+.. code-block:: bash
+
+    $ repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml -b 3.3.0
+    [...]
+    fatal: manifest 'qemu_v8.xml' not available
+    fatal: <linkfile> invalid "src": ../toolchains/aarch64/bin/aarch64-linux-gnu-gdb: bad component: ..
+
+The workaround is to checkout repo version ``1.13.9`` manually:
+
+.. code-block:: bash
+
+    $ repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml -b 3.3.0
+    # Above error occurs, ignore it
+    $ (cd .repo/repo; git checkout v1.13.9)
+    $ repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml -b 3.3.0
+    # Should not error out. Then proceed with 'repo sync' and build.

building/gits/index.rst

@@ -12,6 +12,7 @@ the entire TEE solution.
 
    build
    build_legacy
+   build_legacy_3_1_0-3_8_0
    manifest
    optee_benchmark
    optee_client