Skip to content

Commit

Permalink
doc: document layers
Browse files Browse the repository at this point in the history
  • Loading branch information
rhubert committed Sep 19, 2024
1 parent b0fac7f commit 0a37ba3
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 1 deletion.
1 change: 1 addition & 0 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
76 changes: 76 additions & 0 deletions doc/manpages/bob-layers.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
.. _manpage-layers:

bob-layers
==========

.. only:: not man

Name
----

bob-layers - Handle layers

Synopsis
--------

::

bob layers [-h] [-c CONFIGFILE] [-lc LAYERCONFIG] [-v] [-D DEFINES]
[--attic | --no-attic]
{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
:ref:`bob status <manpage-bob-status>` for a description of the output
fields.

Options
-------

``--attic``
Move layer workspace to attic if inline SCM switching is not possible.
(Default)

``--no-attic``
Do not move layer workspace to attic if inline SCM switching is not possible.
Instead a build error is issued.

``-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.

``-lc LAYERCONFIG``
Use additional layer configuration file.

This is special kind of configuration file to control the layers checkout. Only
``layersWhitelist`` and ``layersScmOverrides`` are supported.

The ``.yaml`` suffix is appended automatically and the configuration file
is searched relative to the project root directory unless an absolute path
is given.

``-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)
1 change: 1 addition & 0 deletions doc/manpages/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Contents:
bob-graph
bob-init
bob-jenkins
bob-layers
bob-ls
bobpaths
bob-project
Expand Down
34 changes: 33 additions & 1 deletion doc/manual/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1927,7 +1927,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::
Expand All @@ -1949,8 +1949,40 @@ 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:
- name: myapp
scm: git
url: [email protected]:myapp.git
commit: ...
- bsp

Only `git`,`svn`,`url` and `cvs` scm's are supported for layers. During layers
checkout the regular ``whitelist`` and ``scmOverrides`` settings are not used.
Instead the checkout could be controlled by ``layersWhitelist`` and
``layersScmOverrides``.

If a scmSpec is given Bob takes care of the layer management:

- layers are checked out / updated during bob-build (except build-only)
- bob layers command to update / show status (see :ref:`manpage-layers`).

.. _configuration-config-plugins:

layersWhitelist
~~~~~~~~~~~~~~~

Whitelist for layers update only. See :ref:`configuration-config-whitelist`.

layersScmOverrides
~~~~~~~~~~~~~~~~~~

:ref:`configuration-config-scmOverrides` used by layers checkout / update.
Conditional overrides are not supported.

plugins
~~~~~~~

Expand Down

0 comments on commit 0a37ba3

Please sign in to comment.