From 55308d0a61cfba5c7895985c4dca79ca0bd2a5ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Kl=C3=B6tzke?= <jan@kloetzke.net> Date: Fri, 1 Nov 2024 21:28:11 +0100 Subject: [PATCH] doc: document mangedLayers policy --- doc/manual/configuration.rst | 4 +++ doc/manual/policies.rst | 54 ++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/doc/manual/configuration.rst b/doc/manual/configuration.rst index e7b86645..56689a3a 100644 --- a/doc/manual/configuration.rst +++ b/doc/manual/configuration.rst @@ -1968,6 +1968,10 @@ possibility is to provide an SCM-Dictionary (see commit: ... - bsp +.. note:: + Managed layers are only supported if the :ref:`policies-managedLayers` + policy is set to the new behaviour. + If a layer SCM specification is given, Bob takes care of the layer management: - Layers are checked out / updated during bob-build (except build-only). diff --git a/doc/manual/policies.rst b/doc/manual/policies.rst index 7dbd1503..9e07dcb5 100644 --- a/doc/manual/policies.rst +++ b/doc/manual/policies.rst @@ -290,6 +290,60 @@ Old behavior New behavior Apply string substitution to ``metaEnvironment`` variables. +.. _policies-managedLayers: + +managedLayers +~~~~~~~~~~~~~ + +Introduced in: 0.25 + +Starting with Bob version 0.25, managed layers are supported. This changed the +location where layers are stored, though. Historically, layers could be nested +where they would form a tree structure. That is, each layer can have a ``layers`` +directory itself where further layers are located. Because this does not work +if multiple layers refer to another common layer, the directory structure +has been flattened. + +Old behavior + Keep support for projects that were created before Bob 0.25. Layers with + sub-layers form a tree structure. See the following example:: + + . + ├── config.yaml + ├── layers + │ └── foo + │ ├── config.yaml + │ ├── layers + │ │ ├── bar + │ │ │ └── recipes + │ │ └── baz + │ │ └── recipes + │ └── recipes + └── recipes + + No SCM can be used in the :ref:`configuration-config-layers` section of + ``config.yaml``. The :ref:`manpage-layers` command will refuse to work on + such projectes. + +New behavior + Managed layers are supported, that is SCMs can be used in the + :ref:`configuration-config-layers` section of ``config.yaml``. The layers + are checked out flat into the ``layers`` directory of the project:: + + . + ├── config.yaml + ├── layers + │ ├── bar + │ │ └── recipes + │ ├── baz + │ │ └── recipes + │ └── foo + │ ├── config.yaml + │ └── recipes + └── recipes + + Unmanaged layers are expected in the same directory. + .. _policies-obsolete: Obsolete policies