doc: document layers-scm

doc/conf.py

@@ -267,6 +267,7 @@ def __getattr__(cls, name):
     ('manpages/bob-graph', 'bob-graph', 'Generate dependency graph', ['Ralf Hubert'], 1),
     ('manpages/bob-init', 'bob-init', 'Initialize out-of-source build tree', ['Jan Klötzke'], 1),
     ('manpages/bob-jenkins', 'bob-jenkins', 'Configure Jenkins server', ['Jan Klötzke'], 1),
+    ('manpages/bob-layers', 'bob-layers', 'Manage Layers', ['BobBuildTool Team'], 1),
     ('manpages/bob-ls', 'bob-ls', 'List package hierarchy', ['Jan Klötzke'], 1),
     ('manpages/bobpaths', 'bobpaths', 'Specifying paths to Bob packages', ['Jan Klötzke'], 7),
     ('manpages/bob-project', 'bob-project', 'Create IDE project files', ['Jan Klötzke'], 1),

doc/manpages/bob-layers.rst

@@ -0,0 +1,58 @@
+.. _manpage-layers:
+
+bob-layers
+==========
+
+.. only:: not man
+
+   Name
+   ----
+
+   bob-layers - Handle layers
+
+Synopsis
+--------
+
+::
+
+    bob show [-h] [-c CONFIGFILE] [-v] [-D DEFINES] {update,status}
+
+
+Description
+-----------
+
+Update layers or show their scm-status. The following sub-commands are
+available:
+
+``update``
+
+Updates the layers.
+
+``status``
+
+Show the scm-status of each layer and optionally list modifications. See
+`man bob-status` for a description of the output fields.
+
+Options
+-------
+
+``-c CONFIGFILE``
+    Use additional configuration file.
+
+    The ``.yaml`` suffix is appended automatically and the configuration file
+    is searched relative to the project root directory unless an absolute path
+    is given. Bob will parse these user configuration files after
+    *default.yaml*. They are using the same schema.
+
+    This option can be given multiple times. The files will be parsed in the
+    order as they appeared on the command line.
+
+``-D VAR=VALUE``
+    Override default or set environment variable.
+
+    Sets the variable ``VAR`` to ``VALUE``. This overrides the value possibly
+    set by ``default.yaml``, config files passed by ``-c`` or any file that was
+    included by either of these files.
+
+``-v, --verbose``
+    Increase verbosity (may be specified multiple times)

doc/manpages/index.rst

@@ -14,6 +14,7 @@ Contents:
    bob-graph
    bob-init
    bob-jenkins
+   bob-layers
    bob-ls
    bobpaths
    bob-project

doc/manual/configuration.rst

@@ -1900,7 +1900,7 @@ equal.
 layers
 ~~~~~~
 
-Type: List of strings
+Type: List of strings or SCM-Dictionary or List of SCM-Dictionaries
 
 The ``layers`` section consists of a list of layer names that are then expected
 in the ``layers`` directory relative to the ``conig.yaml`` referencing them::
@@ -1922,6 +1922,23 @@ of lower precedence.
 
 See :ref:`configuration` for more information.
 
+Typically layers have their own VCS. To provide them to the root-recipes common
+VCS-methods like git-submodules can be used. Another possibility is to provide a
+SCM-Dictionary (see :ref:`configuration-recipes-scm`)::
+
+    layers:
+        - myapp
+            - scm: git
+              url: [email protected]:myapp.git
+              commit: ...
+        - bsp
+
+Using this Bob takes care of the layer managment and would checkout the layers
+if they do not exists, update the layers if the spec changed during regular
+build (except `build-only` is used) and allows you to use `bob layers`.
+
+See :ref:`manpage-layers`.
+
 .. _configuration-config-plugins:
 
 plugins