Lines Matching +full:- +full:- +full:build +full:- +full:only
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
8 or more Zephyr build systems and optional additional build systems
9 into a hierarchical build system.
11 For example, you can use sysbuild to build a Zephyr application together
19 Like Zephyr's :ref:`build system <build_overview>`, sysbuild is written in
27 Single-image build
29 build system.
31 Multi-image build
32 When sysbuild is used to manage multiple build systems.
34 application images from each build system.
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.
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,
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
64 the ``BOARD`` variable, these are shared among multiple build systems.
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
73 :file:`runners.yaml` files that each Zephyr build system will contain. These
74 are packaged into a global view of how to flash and debug each build system
77 - Build names are prefixed with the target name and an underscore, for example
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
94 the ``west build documentation``.
96 .. zephyr-app-commands::
98 :zephyr-app: samples/hello_world
100 :goals: build
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
117 To turn this off, run this before generating your build system:
119 .. code-block:: shell
121 west config build.sysbuild False
123 To turn this off for just one ``west build`` command, run:
125 .. code-block:: shell
127 west build --no-sysbuild ...
129 .. group-tab:: ``cmake``
133 .. zephyr-app-commands::
137 :goals: build
138 :gen-args: -DAPP_DIR=samples/hello_world
142 project as the source folder, and give ``-DAPP_DIR=<path-to-sample>`` as
150 settings and Kconfig build options given on the command line as
151 ``-D<var>=<value>`` or ``-DCONFIG_<var>=<value>`` are handled by the Zephyr
152 build system.
154 However, when sysbuild combines multiple Zephyr build systems, there could be
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
171 :goals: build
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::
182 :goals: build
183 …:gen-args: -DAPP_DIR=samples/hello_world -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_DEBUG_OPTIMIZAT…
193 CMake variable settings can be passed to CMake using ``-D<var>=<value>`` on the
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
206 -D<namespace>_<var>=<value>
209 build system to the value ``BAR``, run the following commands:
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 ...
232 -DSB_CONFIG_<var>=<value>
239 -D<namespace>_CONFIG_<var>=<value>
245 build system to the value ``BAR``, run the following commands:
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
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
283 You can use :ref:`west flash <west-flashing>` to flash applications with
286 When invoking ``west flash`` on a build consisting of multiple images, each
287 image is flashed in sequence. Extra arguments such as ``--runner jlink`` are
290 For more details, see :ref:`west-multi-domain-flashing`.
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`.
310 To build a sample like ``hello_world`` with MCUboot,
311 enable MCUboot and build and flash the sample as follows:
315 .. group-tab:: ``west build``
317 .. zephyr-app-commands::
319 :zephyr-app: samples/hello_world
321 :goals: build
322 :west-args: --sysbuild
323 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
326 .. group-tab:: ``cmake``
328 .. zephyr-app-commands::
332 :goals: build
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
355 ``sysbuild.conf`` in the application top-level directory.
360 .. code-block:: none
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
380 .. group-tab:: ``west build``
382 .. zephyr-app-commands::
384 :zephyr-app: samples/hello_world
386 :goals: build
387 :west-args: --sysbuild
388 :gen-args: -DSB_CONF_FILE=sysbuild-mcuboot.conf
391 .. group-tab:: ``cmake``
393 .. zephyr-app-commands::
397 :goals: build
398 :gen-args: -DAPP_DIR=samples/hello_world -DSB_CONF_FILE=sysbuild-mcuboot.conf
404 Sysbuild creates build targets for each image (including sysbuild itself) for
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
420 Dedicated image build targets
423 Not all build targets for images are given equivalent prefixed build targets
424 when sysbuild is used, for example build targets like ``ram_report``,
426 When using :ref:`Trusted Firmware <tfm_build_system>`, this includes build
428 and ``bl2_ram_report``. To run these build targets, the build directory of the
429 image can be provided to west/ninja/make along with the name of the build
434 .. group-tab:: ``west``
437 using sysbuild with mcuboot enabled in the default ``build`` folder
438 location, the ``rom_report`` build target for ``mcuboot`` can be ran
441 .. code-block:: shell
443 west build -d build/mcuboot -t rom_report
445 .. group-tab:: ``ninja``
449 build target for ``mcuboot`` can be ran with:
451 .. code-block:: shell
453 ninja -C mcuboot rom_report
455 .. group-tab:: ``make``
459 build target for ``mcuboot`` can be ran with:
461 .. code-block:: shell
463 make -C mcuboot rom_report
481 .. code-block:: cmake
485 SOURCE_DIR <path-to>/my_sample
488 This could be useful, for example, if your board requires you to build and flash an
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
506 .. code-block:: cmake
510 SOURCE_DIR <path-to>/my_sample
529 .. code-block:: none
539 .. code-block:: cmake
544 SOURCE_DIR <path-to>/second_sample
550 .. code-block:: kconfig
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,
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
604 Sysbuild also allows users to change :ref:`application-configuration-directory`
608 ----------------------------------------------------------
618 .. code-block:: cfg
624 ------------------------------------------
634 .. code-block:: none
650 be used when ``my_sample`` is included in the build, and the default
659 ----------------------------
662 (see :ref:`application-file-suffixes` for details on this feature in applications). For sysbuild,
664 file will have this value applied and used (instead of the build type) if the file exists.
668 .. code-block:: none
698 The ``FILE_SUFFIX`` can also be applied only to single images by prefixing the variable with the
703 .. group-tab:: ``west build``
705 .. zephyr-app-commands::
709 :goals: build
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::
720 :goals: build
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
731 information from one application's build system to be available to another's,
745 .. code-block:: cmake
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
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
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