Skip to content

Commit

Permalink
doc: sysbuild: Add documentation for image ordering
Browse files Browse the repository at this point in the history
Add a brief subsection to explain `sysbuild_add_dependencies()`.

Signed-off-by: Grzegorz Swiderski <grzegorz.swiderski@nordicsemi.no>
  • Loading branch information
57300 committed May 23, 2023
1 parent 6a5ce89 commit 5535dce
Showing 1 changed file with 45 additions and 0 deletions.
45 changes: 45 additions & 0 deletions doc/build/sysbuild/index.rst
Expand Up @@ -619,6 +619,51 @@ configuration files for ``my_sample`` will be ignored.
This give you full control on how images are configured when integrating those
with ``application``.

.. _sysbuild_zephyr_application_dependencies:

Adding dependencies among Zephyr applications
=============================================

Sometimes, in a multi-image build, you may want certain Zephyr applications to
be configured or flashed in a specific order. For example, if you need some
information from one application's build system to be available to another's,
then the first thing to do is to add a configuration dependency between them.
Separately, you can also add flashing dependencies to control the sequence of
images used by ``west flash``; this could be used if a specific flashing order
is required by an SoC, a _runner_, or something else.

By default, sysbuild will configure and flash applications in the order that
they are added, as ``ExternalZephyrProject_Add()`` calls are processed by CMake,
but this order is not well defined. To make adjustments according to your needs,
you can use the ``sysbuild_add_dependencies()`` function. Its usage is similar
to the standard ``add_dependencies()`` function in CMake.

Here is an example of adding configuration dependencies for ``my_sample``:

.. code-block:: cmake
sysbuild_add_dependencies(IMAGE CONFIGURE my_sample sample_a sample_b)
This will ensure that sysbuild will run CMake for ``sample_a`` and ``sample_b``
(in some order) before doing the same for ``my_sample``, when building these
domains in a single invocation.

If you want to add flashing dependencies instead, then do it like this:

.. code-block:: cmake
sysbuild_add_dependencies(IMAGE FLASH my_sample sample_a sample_b)
As a result, ``my_sample`` will be flashed after ``sample_a`` and ``sample_b``
(in some order), when flashing these domains in a single invocation.

.. tip::

Unlike with ``add_dependencies()``, you are allowed to use
``sysbuild_add_dependencies()`` with non-existent images. This makes it
possible to define relationships between various images in the build system,
regardless of whether they are present in the current multi-image build.

Adding non-Zephyr applications to sysbuild
******************************************

Expand Down

0 comments on commit 5535dce

Please sign in to comment.