Lines Matching +full:extra +full:- +full:user +full:- +full:files
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
27 Single-image build
31 Multi-image build
39 Multi-domain
45 This figure is an overview of sysbuild's inputs, outputs, and user interfaces:
50 :figclass: align-center
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,
59 shown above as ELF, BIN, and HEX files.
61 - You can configure sysbuild or any of the build systems it manages using
66 - Sysbuild itself is also configured using Kconfig. For example, you can
68 link your main Zephyr application as an MCUboot-bootable image, using sysbuild's
69 Kconfig files.
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
73 :file:`runners.yaml` files that each Zephyr build system will contain. These
77 - Build names are prefixed with the target name and an underscore, for example
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
113 Since sysbuild supports both single- and multi-image builds, this lets you
119 .. code-block:: shell
125 .. code-block:: shell
127 west build --no-sysbuild ...
129 .. group-tab:: ``cmake``
133 .. zephyr-app-commands::
138 :gen-args: -DAPP_DIR=samples/hello_world
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
152 environment variable and invoke the build with ``cmake --build``, for example:
154 .. code-block:: shell
156 CMAKE_BUILD_PARALLEL_LEVEL=<n> cmake --build .
160 .. code-block:: shell
162 VERBOSE=1 cmake --build .
170 ``-D<var>=<value>`` or ``-DCONFIG_<var>=<value>`` are handled by the Zephyr
179 The following example shows how to build :zephyr:code-sample:`hello_world` with MCUboot enabled,
184 .. group-tab:: ``west build``
186 .. zephyr-app-commands::
188 :zephyr-app: samples/hello_world
191 :west-args: --sysbuild
192 …:gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZATIONS=y -Dmcuboot_CONFIG_DEBUG_…
195 .. group-tab:: ``cmake``
197 .. zephyr-app-commands::
202 …:gen-args: -DAPP_DIR=samples/hello_world -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZAT…
212 CMake variable settings can be passed to CMake using ``-D<var>=<value>`` on the
214 ``-DCONFIG_<var>=<value>`` or ``-D<namespace>_CONFIG_<var>=<value>``.
225 -D<namespace>_<var>=<value>
232 .. group-tab:: ``west build``
234 .. code-block:: shell
236 west build --sysbuild ... -- -Dmy_sample_FOO=BAR
238 .. group-tab:: ``cmake``
240 .. code-block:: shell
242 cmake -Dmy_sample_FOO=BAR ...
251 -DSB_CONFIG_<var>=<value>
258 -D<namespace>_CONFIG_<var>=<value>
268 .. group-tab:: ``west build``
270 .. code-block:: shell
272 west build --sysbuild ... -- -Dmy_sample_CONFIG_FOO=BAR
274 .. group-tab:: ``cmake``
276 .. code-block:: shell
278 cmake -Dmy_sample_CONFIG_FOO=BAR ...
284 This means that passing ``-DCONFIG_<var>=<value>`` and
285 ``-Dmy_sample_CONFIG_<var>=<value>`` are equivalent.
291 .. code-block:: shell
293 west build -b <board> my_sample -- -DCONFIG_FOO=BAR
295 .. code-block:: shell
297 west build -b <board> --sysbuild my_sample -- -DCONFIG_FOO=BAR
302 You can use :ref:`west flash <west-flashing>` to flash applications with
306 image is flashed in sequence. Extra arguments such as ``--runner jlink`` are
309 For more details, see :ref:`west-multi-domain-flashing`.
315 Just follow the existing :ref:`west debug <west-debugging>` guide to debug the main sample.
318 the ``--domain`` argument, as follows::
320 west debug --domain mcuboot
322 For more details, see :ref:`west-multi-domain-debugging`.
334 .. group-tab:: ``west build``
336 .. zephyr-app-commands::
338 :zephyr-app: samples/hello_world
341 :west-args: --sysbuild
342 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
345 .. group-tab:: ``cmake``
347 .. zephyr-app-commands::
352 :gen-args: -DAPP_DIR=samples/hello_world -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
366 flashing only MCUBoot, for example using ``west flash --domain mcuboot``, may
373 configuration files. By default, sysbuild looks for a configuration file named
374 ``sysbuild.conf`` in the application top-level directory.
379 .. code-block:: none
387 .. code-block:: cfg
392 ``-DSB_CONF_FILE=<sysbuild-conf-file>`` CMake build setting.
394 For example, you can create ``sysbuild-mcuboot.conf`` and then
399 .. group-tab:: ``west build``
401 .. zephyr-app-commands::
403 :zephyr-app: samples/hello_world
406 :west-args: --sysbuild
407 :gen-args: -DSB_CONF_FILE=sysbuild-mcuboot.conf
410 .. group-tab:: ``cmake``
412 .. zephyr-app-commands::
417 :gen-args: -DAPP_DIR=samples/hello_world -DSB_CONF_FILE=sysbuild-mcuboot.conf
433 ``mcuboot_``, using ninja or make - for details on how to run image build
453 .. group-tab:: ``west``
460 .. code-block:: shell
462 west build -d build/mcuboot -t rom_report
464 For TF-M projects using TF-M targets, the application build directory is
467 .. code-block:: shell
469 west build -d build/<app_name> -t tfm_rom_report
471 .. group-tab:: ``ninja``
477 .. code-block:: shell
479 ninja -C mcuboot rom_report
481 For TF-M projects using TF-M targets, the application build directory is
484 .. code-block:: shell
486 ninja -C <app_name> -t tfm_rom_report
488 .. group-tab:: ``make``
494 .. code-block:: shell
496 make -C mcuboot rom_report
498 For TF-M projects using TF-M targets, the application build directory is
501 .. code-block:: shell
503 make -C <app_name> -t tfm_rom_report
521 .. code-block:: cmake
525 SOURCE_DIR <path-to>/my_sample
529 SoC-specific bootloader along with your main application.
537 * A specific core on a physical board with a multi-core SoC, such as
546 .. code-block:: cmake
550 SOURCE_DIR <path-to>/my_sample
561 You can control whether extra applications are included as sysbuild domains
564 If the extra application image is specific to the board or an application,
565 you can create two additional files: :file:`sysbuild.cmake` and :file:`Kconfig.sysbuild`.
569 .. code-block:: none
579 .. code-block:: cmake
584 SOURCE_DIR <path-to>/second_sample
590 .. code-block:: kconfig
607 You can mark ``my_sample`` as a build-only application in this manner:
609 .. code-block:: cmake
613 SOURCE_DIR <path-to>/my_sample
619 Instead, you may use the outputs of this domain for other purposes - for example,
623 a Kconfig option, which would make ``my_sample`` conditionally build-only.
627 Applications marked as build-only can still be flashed manually, using
628 ``west flash --domain my_sample``. As such, the ``BUILD_ONLY`` option only
637 configuration files from the application (MCUboot) itself will be used.
640 necessary to make adjustments to the configuration of extra images.
644 Sysbuild also allows users to change :ref:`application-configuration-directory`
648 ----------------------------------------------------------
658 .. code-block:: cfg
664 ------------------------------------------
671 :file:`sysbuild/my_sample/` folder and place any configuration files in
674 .. code-block:: none
689 All configuration files under the :file:`sysbuild/my_sample/` folder will now
691 configuration files for ``my_sample`` will be ignored.
699 ----------------------------
702 (see :ref:`application-file-suffixes` for details on this feature in applications). For sysbuild,
708 .. code-block:: none
734 files without the suffix). Sysbuild itself will use the ``sysbuild_test_key.conf`` Kconfig
743 .. group-tab:: ``west build``
745 .. zephyr-app-commands::
750 :west-args: --sysbuild
751 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -Dmcuboot_FILE_SUFFIX="max_log"
754 .. group-tab:: ``cmake``
756 .. zephyr-app-commands::
761 … :gen-args: -DAPP_DIR=<app_dir> -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -Dmcuboot_FILE_SUFFIX="max_log"
769 Sometimes, in a multi-image build, you may want certain Zephyr applications to
785 .. code-block:: cmake
795 .. code-block:: cmake
804 Adding flashing dependencies is not allowed for build-only applications.
808 Adding non-Zephyr applications to sysbuild
811 You can include non-Zephyr applications in a multi-image build using the
815 When using ``ExternalProject``, the non-Zephyr application will be built as
820 .. _MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr
834 .. code-block:: cmake
836 # Place pre-sysbuild configuration items here
852 .. code-block:: cmake
854 list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../<extra-board-root>)
870 Modules can be extended by adding custom CMake or Kconfig files as normal
871 :ref:`modules <module-yml>` do, this will cause the files to be included in
873 :ref:`sysbuild-specific module extension <sysbuild_module_integration>` files
874 which can be used to include CMake and Kconfig files for the overall sysbuild