Lines Matching +full:sysbuild +full:- +full:cmake
3 Sysbuild (System build)
6 Sysbuild is a higher-level build system that can be used to combine multiple
7 other build systems together. It is a higher-level layer that combines one
11 For example, you can use sysbuild to build a Zephyr application together
15 Sysbuild works by configuring and building at least a Zephyr application and, optionally, as many
19 Like Zephyr's :ref:`build system <build_overview>`, sysbuild is written in
20 CMake and uses :ref:`Kconfig <kconfig>`.
27 Single-image build
28 When sysbuild is used to create and manage just one Zephyr application's
31 Multi-image build
32 When sysbuild is used to manage multiple build systems.
37 Every Zephyr CMake build system managed by sysbuild.
39 Multi-domain
40 When more than one Zephyr CMake build system (domain) is managed by sysbuild.
45 This figure is an overview of sysbuild's inputs, outputs, and user interfaces:
47 .. figure:: sysbuild.svg
49 :alt: Sysbuild architectural overview
50 :figclass: align-center
53 The following are some key sysbuild features indicated in this figure:
55 - You can run sysbuild either with :ref:`west build
56 <west-building>` or directly via ``cmake``.
58 - You can use sysbuild to generate application images from each build system,
61 - You can configure sysbuild or any of the build systems it manages using
63 sysbuild can direct them to the right build system. In some cases, such as
66 - Sysbuild itself is also configured using Kconfig. For example, you can
67 instruct sysbuild to build the MCUboot bootloader, as well as to build and
68 link your main Zephyr application as an MCUboot-bootable image, using sysbuild's
71 - Sysbuild integrates with west's :ref:`west-build-flash-debug` commands. It
72 does this by managing the :ref:`west-runner`, and specifically the
75 in a :file:`domains.yaml` file generated and managed by sysbuild.
77 - Build names are prefixed with the target name and an underscore, for example
78 the sysbuild target is prefixed with ``sysbuild_`` and if MCUboot is enabled
79 as part of sysbuild, it will be prefixed with ``mcuboot_``. This also allows
81 ninja) ``ninja sysbuild_menuconfig`` to configure sysbuild or (if using make)
84 Building with sysbuild
87 As mentioned above, you can run sysbuild via ``west build`` or ``cmake``.
91 .. group-tab:: ``west build``
93 Here is an example. For details, see :ref:`west-multi-domain-builds` in
96 .. zephyr-app-commands::
98 :zephyr-app: samples/hello_world
101 :west-args: --sysbuild
106 To configure ``west build`` to use ``--sysbuild`` by default from now on,
109 .. code-block:: shell
111 west config build.sysbuild True
113 Since sysbuild supports both single- and multi-image builds, this lets you
114 use sysbuild all the time, without worrying about what type of build you are
119 .. code-block:: shell
121 west config build.sysbuild False
125 .. code-block:: shell
127 west build --no-sysbuild ...
129 .. group-tab:: ``cmake``
131 Here is an example using CMake and Ninja.
133 .. zephyr-app-commands::
134 :tool: cmake
135 :app: share/sysbuild
138 :gen-args: -DAPP_DIR=samples/hello_world
141 To use sysbuild directly with CMake, you must specify the sysbuild
142 project as the source folder, and give ``-DAPP_DIR=<path-to-sample>`` as
143 an extra CMake argument. ``APP_DIR`` is the path to the main Zephyr
144 application managed by sysbuild.
149 When building a single Zephyr application without sysbuild, all CMake cache
151 ``-D<var>=<value>`` or ``-DCONFIG_<var>=<value>`` are handled by the Zephyr
154 However, when sysbuild combines multiple Zephyr build systems, there could be
155 Kconfig settings exclusive to sysbuild (and not used by any of the applications).
156 To handle this, sysbuild has namespaces for configuration variables. You can use these
157 namespaces to direct settings either to sysbuild itself or to a specific Zephyr
158 application managed by sysbuild using the information in these sections.
160 The following example shows how to build :zephyr:code-sample:`hello_world` with MCUboot enabled,
165 .. group-tab:: ``west build``
167 .. zephyr-app-commands::
169 :zephyr-app: samples/hello_world
172 :west-args: --sysbuild
173 …:gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZATIONS=y -Dmcuboot_CONFIG_DEBUG_…
176 .. group-tab:: ``cmake``
178 .. zephyr-app-commands::
179 :tool: cmake
180 :app: share/sysbuild
183 …:gen-args: -DAPP_DIR=samples/hello_world -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZAT…
190 CMake variable namespacing
193 CMake variable settings can be passed to CMake using ``-D<var>=<value>`` on the
194 command line. You can also set Kconfig options via CMake as
195 ``-DCONFIG_<var>=<value>`` or ``-D<namespace>_CONFIG_<var>=<value>``.
197 Since sysbuild is the entry point for the build system, and sysbuild is written
198 in CMake, all CMake variables are first processed by sysbuild.
200 Sysbuild creates a namespace for each domain. The namespace prefix is the
206 -D<namespace>_<var>=<value>
208 For example, to set the CMake variable ``FOO`` in the ``my_sample`` application
213 .. group-tab:: ``west build``
215 .. code-block:: shell
217 west build --sysbuild ... -- -Dmy_sample_FOO=BAR
219 .. group-tab:: ``cmake``
221 .. code-block:: shell
223 cmake -Dmy_sample_FOO=BAR ...
230 To set the sysbuild Kconfig option ``<var>`` to the value ``<value>``, use this syntax::
232 -DSB_CONFIG_<var>=<value>
234 In the previous example, ``SB_CONFIG`` is the namespace prefix for sysbuild's Kconfig
239 -D<namespace>_CONFIG_<var>=<value>
249 .. group-tab:: ``west build``
251 .. code-block:: shell
253 west build --sysbuild ... -- -Dmy_sample_CONFIG_FOO=BAR
255 .. group-tab:: ``cmake``
257 .. code-block:: shell
259 cmake -Dmy_sample_CONFIG_FOO=BAR ...
265 This means that passing ``-DCONFIG_<var>=<value>`` and
266 ``-Dmy_sample_CONFIG_<var>=<value>`` are equivalent.
268 This allows you to build the same application with or without sysbuild using
269 the same syntax for setting Kconfig values at CMake time.
272 .. code-block:: shell
274 west build -b <board> my_sample -- -DCONFIG_FOO=BAR
276 .. code-block:: shell
278 west build -b <board> --sysbuild my_sample -- -DCONFIG_FOO=BAR
280 Sysbuild flashing using ``west flash``
283 You can use :ref:`west flash <west-flashing>` to flash applications with
284 sysbuild.
287 image is flashed in sequence. Extra arguments such as ``--runner jlink`` are
290 For more details, see :ref:`west-multi-domain-flashing`.
292 Sysbuild debugging using ``west debug``
295 You can use ``west debug`` to debug the main application, whether you are using sysbuild or not.
296 Just follow the existing :ref:`west debug <west-debugging>` guide to debug the main sample.
299 the ``--domain`` argument, as follows::
301 west debug --domain mcuboot
303 For more details, see :ref:`west-multi-domain-debugging`.
308 Sysbuild supports MCUboot natively.
315 .. group-tab:: ``west build``
317 .. zephyr-app-commands::
319 :zephyr-app: samples/hello_world
322 :west-args: --sysbuild
323 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
326 .. group-tab:: ``cmake``
328 .. zephyr-app-commands::
329 :tool: cmake
330 :app: share/sysbuild
333 :gen-args: -DAPP_DIR=samples/hello_world -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
347 flashing only MCUBoot, for example using ``west flash --domain mcuboot``, may
350 Sysbuild Kconfig file
353 You can set sysbuild's Kconfig options for a single application using
354 configuration files. By default, sysbuild looks for a configuration file named
355 ``sysbuild.conf`` in the application top-level directory.
357 In the following example, there is a :file:`sysbuild.conf` file that enables building and flashing …
358 MCUboot whenever sysbuild is used:
360 .. code-block:: none
365 └── sysbuild.conf
368 .. code-block:: cfg
373 ``-DSB_CONF_FILE=<sysbuild-conf-file>`` CMake build setting.
375 For example, you can create ``sysbuild-mcuboot.conf`` and then
376 specify this file when building with sysbuild, as follows:
380 .. group-tab:: ``west build``
382 .. zephyr-app-commands::
384 :zephyr-app: samples/hello_world
387 :west-args: --sysbuild
388 :gen-args: -DSB_CONF_FILE=sysbuild-mcuboot.conf
391 .. group-tab:: ``cmake``
393 .. zephyr-app-commands::
394 :tool: cmake
395 :app: share/sysbuild
398 :gen-args: -DAPP_DIR=samples/hello_world -DSB_CONF_FILE=sysbuild-mcuboot.conf
401 Sysbuild targets
404 Sysbuild creates build targets for each image (including sysbuild itself) for
411 For the main application (as is the same without using sysbuild) these can be
412 ran normally without any prefix. For other images (including sysbuild), these
414 ``mcuboot_``, using ninja or make - for details on how to run image build
415 targets that do not have mapped build targets in sysbuild, see the
424 when sysbuild is used, for example build targets like ``ram_report``,
434 .. group-tab:: ``west``
437 using sysbuild with mcuboot enabled in the default ``build`` folder
441 .. code-block:: shell
443 west build -d build/mcuboot -t rom_report
445 .. group-tab:: ``ninja``
447 Assuming that a project has been configured using ``cmake`` and built
448 using ``ninja`` using sysbuild with mcuboot enabled, the ``rom_report``
451 .. code-block:: shell
453 ninja -C mcuboot rom_report
455 .. group-tab:: ``make``
457 Assuming that a project has been configured using ``cmake`` and built
458 using ``make`` using sysbuild with mcuboot enabled, the ``rom_report``
461 .. code-block:: shell
463 make -C mcuboot rom_report
467 Adding Zephyr applications to sysbuild
471 applications as sysbuild domains. Call this CMake function from your
472 application's :file:`sysbuild.cmake` file, or any other CMake file you know will
473 run as part sysbuild CMake invocation.
478 To include ``my_sample`` as another sysbuild domain, targeting the same board
481 .. code-block:: cmake
485 SOURCE_DIR <path-to>/my_sample
489 SoC-specific bootloader along with your main application.
494 In sysbuild and Zephyr CMake build system a board may refer to:
497 * A specific core on a physical board with a multi-core SoC, such as
504 a CMake function call that is structured as follows:
506 .. code-block:: cmake
510 SOURCE_DIR <path-to>/my_sample
521 You can control whether extra applications are included as sysbuild domains
525 you can create two additional files: :file:`sysbuild.cmake` and :file:`Kconfig.sysbuild`.
529 .. code-block:: none
534 ├── Kconfig.sysbuild
535 └── sysbuild.cmake
537 In the previous example, :file:`sysbuild.cmake` would be structured as follows:
539 .. code-block:: cmake
544 SOURCE_DIR <path-to>/second_sample
548 :file:`Kconfig.sysbuild` would be structured as follows:
550 .. code-block:: kconfig
552 source "sysbuild/Kconfig"
561 For more information on setting sysbuild Kconfig options,
567 You can mark ``my_sample`` as a build-only application in this manner:
569 .. code-block:: cmake
573 SOURCE_DIR <path-to>/my_sample
577 As a result, ``my_sample`` will be built as part of the sysbuild build invocation,
579 Instead, you may use the outputs of this domain for other purposes - for example,
582 You can also replace ``TRUE`` with another boolean constant in CMake, such as
583 a Kconfig option, which would make ``my_sample`` conditionally build-only.
587 Applications marked as build-only can still be flashed manually, using
588 ``west flash --domain my_sample``. As such, the ``BUILD_ONLY`` option only
596 When adding a Zephyr application to sysbuild, such as MCUboot, then the
602 Sysbuild gives users the ability of creating Kconfig fragments or devicetree
604 Sysbuild also allows users to change :ref:`application-configuration-directory`
608 ----------------------------------------------------------
611 overlay under a sysbuild folder, where the name of the file is
613 application includes ``my_sample`` then create a :file:`sysbuild/my_sample.conf`
614 file or a devicetree overlay :file:`sysbuild/my_sample.overlay`.
618 .. code-block:: cfg
620 # sysbuild/my_sample.conf
624 ------------------------------------------
627 :file:`sysbuild/<image>/`.
631 :file:`sysbuild/my_sample/` folder and place any configuration files in
634 .. code-block:: none
639 └── sysbuild
649 All configuration files under the :file:`sysbuild/my_sample/` folder will now
658 Sysbuild file suffix support
659 ----------------------------
661 File suffix support through the :makevar:`FILE_SUFFIX` is supported in sysbuild
662 (see :ref:`application-file-suffixes` for details on this feature in applications). For sysbuild,
668 .. code-block:: none
673 ├── sysbuild.conf
675 └── sysbuild
682 ``my_sample.conf`` Kconfig fragment file. Sysbuild itself will use the ``sysbuild.conf``
688 file without the suffix). Sysbuild itself will use the ``sysbuild.conf`` Kconfig fragment file
694 files without the suffix). Sysbuild itself will use the ``sysbuild_test_key.conf`` Kconfig
695 fragment file. This can be used to apply a different sysbuild configuration, for example to use
703 .. group-tab:: ``west build``
705 .. zephyr-app-commands::
710 :west-args: --sysbuild
711 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -Dmcuboot_FILE_SUFFIX="max_log"
714 .. group-tab:: ``cmake``
716 .. zephyr-app-commands::
717 :tool: cmake
718 :app: share/sysbuild
721 … :gen-args: -DAPP_DIR=<app_dir> -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -Dmcuboot_FILE_SUFFIX="max_log"
729 Sometimes, in a multi-image build, you may want certain Zephyr applications to
737 By default, sysbuild will configure and flash applications in the order that
738 they are added, as ``ExternalZephyrProject_Add()`` calls are processed by CMake.
741 ``add_dependencies()`` function in CMake.
745 .. code-block:: cmake
749 This will ensure that sysbuild will run CMake for ``sample_a`` and ``sample_b``
755 .. code-block:: cmake
764 Adding flashing dependencies is not allowed for build-only applications.
768 Adding non-Zephyr applications to sysbuild
771 You can include non-Zephyr applications in a multi-image build using the
772 standard CMake module `ExternalProject`_. Please refer to the CMake
775 When using ``ExternalProject``, the non-Zephyr application will be built as
776 part of the sysbuild build invocation, but ``west flash`` or ``west debug``
780 .. _MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr
781 .. _ExternalProject: https://cmake.org/cmake/help/latest/module/ExternalProject.html
783 Extending sysbuild
786 Sysbuild can be extended by other modules to give it additional functionality
790 Modules can be extended by adding custom CMake or Kconfig files as normal
791 :ref:`modules <module-yml>` do, this will cause the files to be included in
793 :ref:`sysbuild-specific module extension <sysbuild_module_integration>` files
794 which can be used to include CMake and Kconfig files for the overall sysbuild