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:
parent
03514c13b4
commit
62c5b3d198
1 changed files with 150 additions and 54 deletions
|
@ -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:
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue