doc: west: add examples for each topology

Add example west.yml files showing how to build west workspaces of
each type. Split these into separate sections as a result since
they're longer.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2020-02-24 15:01:25 -08:00 committed by Johan Hedberg
commit 62c5b3d198

View file

@ -78,70 +78,166 @@ repository.
Topologies supported
********************
The following three source code topologies supported by west:
The following are example source code topologies supported by west.
* **T1**: Star topology with zephyr as the manifest repository:
- T1: star topology, zephyr is the manifest repository
- T2: star topology, a Zephyr application is the manifest repository
- T3: forest topology, freestanding manifest repository
- The zephyr repository acts as the central repository and includes a
complete list of projects used upstream
- Default (upstream) configuration
- Analogy with existing mechanisms: Git sub-modules with zephyr as the
super-project
- See :ref:`west-installation` for how mainline Zephyr is an example
of this topology
T1: Star topology, zephyr is the manifest repository
====================================================
* **T2**: Star topology with an application repository as the manifest
repository:
- The zephyr repository acts as the central repository and specifies
its :ref:`modules` in its :file:`west.yml`
- Analogy with existing mechanisms: Git submodules with zephyr as the
super-project
- A repository containing a Zephyr application acts as the central repository
and includes a complete list of other projects, including the zephyr
repository, required to build it
- Useful for those focused on a single application
- Analogy with existing mechanisms: Git sub-modules with the application as
the super-project, zephyr and other projects as sub-modules
- An installation using this topology could look like this:
This is the default. See :ref:`west-installation` for how mainline Zephyr is an
example of this topology.
.. code-block:: none
.. _west-t2:
app-manifest-installation
├── application
│   ├── CMakeLists.txt
│   ├── prj.conf
│   ├── src
│   │   └── main.c
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr
T2: Star topology, application is the manifest repository
=========================================================
* **T3**: Forest topology:
- Useful for those focused on a single application
- A repository containing a Zephyr application acts as the central repository
and names other projects required to build it in its :file:`west.yml`. This
includes the zephyr repository and any modules.
- Analogy with existing mechanisms: Git submodules with the application as
the super-project, zephyr and other projects as submodules
- A dedicated manifest repository which contains no Zephyr source code,
and specifies a list of projects all at the same "level"
- Useful for downstream distributions with no "central" repository
- Analogy with existing mechanisms: Google repo-based source distribution
- An installation using this topology could look like this:
An installation using this topology looks like this:
.. code-block:: none
.. code-block:: none
forest
├── app1
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── app2
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── manifest-repo
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr
west-workspace
├── application
│   ├── CMakeLists.txt
│   ├── prj.conf
│   ├── src
│   │   └── main.c
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr
Here is an example :file:`application/west.yml` which uses
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr v2.2.0
and its modules into the application manifest file:
.. code-block:: yaml
# Example T2 west.yml, using manifest imports.
manifest:
remotes:
- name: zephyrproject-rtos
url-base: https://github.com/zephyrproject-rtos
projects:
- name: zephyr
remote: zephyrproject-rtos
revision: v2.2.0
import: true
self:
path: application
You can still selectively "override" individual Zephyr modules if you use
``import:`` in this way; see :ref:`west-manifest-ex1.3` for an example.
Another way to do the same thing is to copy/paste :file:`zephyr/west.yml`
to :file:`application/west.yml`, adding an entry for the zephyr
project itself, like this:
.. code-block:: yaml
# Equivalent to the above, but with manually maintained Zephyr modules.
manifest:
remotes:
- name: zephyrproject-rtos
url-base: https://github.com/zephyrproject-rtos
defaults:
remote: zephyrproject-rtos
projects:
- name: zephyr
revision: v2.2.0
west-commands: scripts/west-commands.yml
- name: net-tools
revision: some-sha-goes-here
path: tools/net-tools
# ... other Zephyr modules go here ...
self:
path: application
(The ``west-commands`` is there for :ref:`west-build-flash-debug` and other
Zephyr-specific :ref:`west-extensions`. It's not necessary when using
``import``.)
The main advantage to using ``import`` is not having to track the revisions of
imported projects separately. In the above example, using ``import`` means
Zephyr's :ref:`module <modules>` versions are automatically determined from the
:file:`zephyr/west.yml` revision, instead of having to be copy/pasted (and
maintained) on their own.
T3: Forest topology
===================
- Useful for those supporting multiple independent applications or downstream
distributions with no "central" repository
- A dedicated manifest repository which contains no Zephyr source code,
and specifies a list of projects all at the same "level"
- Analogy with existing mechanisms: Google repo-based source distribution
An installation using this topology looks like this:
.. code-block:: none
west-workspace
├── app1
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── app2
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── manifest-repo
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr
Here is an example T3 :file:`manifest-repo/west.yml` which uses
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr
v2.2.0 and its modules, then add the ``app1`` and ``app2`` projects:
.. code-block:: yaml
manifest:
remotes:
- name: zephyrproject-rtos
url-base: https://github.com/zephyrproject-rtos
- name: your-git-server
url-base: https://git.example.com/your-company
defaults:
remote: your-git-server
projects:
- name: zephyr
remote: zephyrproject-rtos
revision: v2.2.0
import: true
- name: app1
revision: SOME_SHA_OR_BRANCH_OR_TAG
- name: app2
revision: ANOTHER_SHA_OR_BRANCH_OR_TAG
self:
path: manifest-repo
You can also do this "by hand" by copy/pasting :file:`zephyr/west.yml`
as shown :ref:`above <west-t2>` for the T2 topology, with the same caveats.
.. _west-struct: