Lines Matching +full:sysbuild +full:- +full:cmake
1 .. _west-build-flash-debug:
6 Zephyr provides several :ref:`west extension commands <west-extensions>` for
11 commands, see :ref:`flash-and-debug-support` in the board porting guide.
13 .. Add a per-page contents at the top of the page. This page is nested
21 .. _west-building:
26 .. tip:: Run ``west build -h`` for a quick overview.
29 use :ref:`west config <west-config-cmd>` to configure its behavior.
33 - If there is a Zephyr build directory named :file:`build` in your current
34 working directory, it is incrementally re-compiled. The same is true if you
37 - Otherwise, if you run ``west build`` from a Zephyr application's source
48 west build -b <BOARD>
51 exactly the same name you would supply to CMake if you were to invoke it with:
52 ``cmake -DBOARD=<BOARD>``.
56 You can use the :ref:`west boards <west-boards>` command to list all
60 be compiled there after ``west build`` runs CMake to create a build system in
62 application is incrementally re-compiled there without re-running CMake. You
63 can force CMake to run again with ``--cmake``.
65 You don't need to use the ``--board`` option if you've already got an existing
66 build directory; ``west build`` can figure out the board from the CMake cache.
67 For new builds, the ``--board`` option, :envvar:`BOARD` environment variable,
70 .. _west-multi-domain-builds:
72 Sysbuild (multi-domain builds)
75 :ref:`sysbuild` can be used to create a multi-domain build system combining
78 Use ``--sysbuild`` to select the :ref:`sysbuild` build infrastructure with
81 More detailed information regarding the use of sysbuild can be found in the
82 :ref:`sysbuild` guide.
86 The ``build.sysbuild`` configuration option can be enabled to tell
87 ``west build`` to default build using sysbuild.
88 ``--no-sysbuild`` can be used to disable sysbuild for a specific build.
90 ``west build`` will build all domains through the top-level build folder of the
91 domains specified by sysbuild.
93 A single domain from a multi-domain project can be built by using ``--domain``
101 Forcing CMake to Run Again
102 --------------------------
104 To force a CMake re-run, use the ``--cmake`` (or ``-c``) option::
106 west build -c
109 -----------------------
118 .. _west-building-dirs:
121 ------------------------------------
126 west build -b <BOARD> path/to/source/directory
128 To set the build directory explicitly, use ``--build-dir`` (or ``-d``)::
130 west build -b <BOARD> --build-dir path/to/build/directory
133 ``build.dir-fmt`` configuration option. This lets you name build
136 west config build.dir-fmt "build/{board}/{app}"
138 With the above, running ``west build -b reel_board samples/hello_world`` will
140 :ref:`west-building-config` for more details on this option.
143 -------------------------------
145 To specify the build system target to run, use ``--target`` (or ``-t``).
148 build and run the :zephyr:code-sample:`hello_world` sample for the emulated
151 west build -b qemu_x86 -t run samples/hello_world
153 As another example, to use ``-t`` to list all build system targets::
155 west build -t help
157 As a final example, to use ``-t`` to run the ``pristine`` target, which deletes
160 west build -t pristine
162 .. _west-building-pristine:
165 ---------------
170 To force ``west build`` make the build directory pristine before re-running
171 CMake to generate a build system, use the ``--pristine=always`` (or
172 ``-p=always``) option.
174 Giving ``--pristine`` or ``-p`` without a value has the same effect as giving
177 west build -p -b reel_board samples/hello_world
178 west build -p=always -b reel_board samples/hello_world
182 try to reuse a build directory for a different ``--board``.
184 Using ``--pristine=auto`` makes ``west build`` detect some of these situations
191 See the ``west build`` :ref:`west-building-config` for details.
193 .. _west-building-verbose:
196 --------------
198 To print the CMake and compiler commands run by ``west build``, use the global
199 west verbosity option, ``-v``::
201 west -v build -b reel_board samples/hello_world
203 .. _west-building-generator:
204 .. _west-building-cmake-args:
206 One-Time CMake Arguments
207 ------------------------
209 To pass additional arguments to the CMake invocation performed by ``west
210 build``, pass them after a ``--`` at the end of the command line.
214 Passing additional CMake arguments like this forces ``west build`` to re-run
215 the CMake build configuration step, even if a build system has already been
219 After using ``--`` once to generate the build directory, use ``west build -d
220 <build-dir>`` on subsequent runs to do incremental builds.
222 Alternatively, make your CMake arguments permanent as described in the next
225 For example, to use the Unix Makefiles CMake generator instead of Ninja (which
228 west build -b reel_board -- -G'Unix Makefiles'
232 west build -b reel_board -- -G'Unix Makefiles' -DCMAKE_VERBOSE_MAKEFILE=ON
234 Notice how the ``--`` only appears once, even though multiple CMake arguments
235 are given. All command-line arguments to ``west build`` after a ``--`` are
236 passed to CMake.
238 .. _west-building-dtc-overlay-file:
240 To set :ref:`DTC_OVERLAY_FILE <important-build-vars>` to
241 :file:`enable-modem.overlay`, using that file as a
242 :ref:`devicetree overlay <dt-guide>`::
244 west build -b reel_board -- -DDTC_OVERLAY_FILE=enable-modem.overlay
249 west build -- -DEXTRA_CONF_FILE=file.conf
251 .. _west-building-cmake-config:
253 Permanent CMake Arguments
254 -------------------------
256 The previous section describes how to add CMake arguments for a single ``west
257 build`` command. If you want to save CMake arguments for ``west build`` to use
259 ``build.cmake-args`` configuration option. Whenever ``west build`` runs CMake
261 rules and includes the results in the ``cmake`` command line.
266 <west-building-pristine>` after setting ``build.cmake-args`` to make sure it
272 west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
274 (The extra ``--`` is used to force the rest of the command to be treated as a
275 positional argument. Without it, :ref:`west config <west-config-cmd>` would
276 treat the ``-DVAR=VAL`` syntax as a use of its ``-D`` option.)
278 To enable :makevar:`CMAKE_VERBOSE_MAKEFILE`, so CMake always produces a verbose
281 west config build.cmake-args -- -DCMAKE_VERBOSE_MAKEFILE=ON
283 To save more than one argument in ``build.cmake-args``, use a single string
292 west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_VERBOSE_MAKEFILE=ON"
294 If you want to save your CMake arguments in a separate file instead, you can
295 combine CMake's ``-C <initial-cache>`` option with ``build.cmake-args``. For
297 create a file named :file:`~/my-cache.cmake` with the following contents:
299 .. code-block:: cmake
306 west config build.cmake-args "-C ~/my-cache.cmake"
308 See the `cmake(1) manual page`_ and the `set() command`_ documentation for
312 https://cmake.org/cmake/help/latest/manual/cmake.1.html
315 https://cmake.org/cmake/help/latest/command/set.html
318 --------------------
320 Use ``-o`` to pass options to the underlying build tool.
322 This works with both ``ninja`` (:ref:`the default <west-building-generator>`)
325 For example, to pass ``-dexplain`` to ``ninja``::
327 west build -o=-dexplain
329 As another example, to pass ``--keep-going`` to ``make``::
331 west build -o=--keep-going
333 Note that using ``-o=--foo`` instead of ``-o --foo`` is required to prevent
334 ``--foo`` from being treated as a ``west build`` option.
337 -----------------
340 one. You can control this explicitly with the ``-j`` option supported by both
345 west build -o=-j4
347 The ``-o`` option is described further in the previous section.
350 ---------------------
352 In a multi-domain build with :zephyr:code-sample:`hello_world` and `MCUboot`_, you can use
353 ``--domain hello_world`` to only build this domain::
355 west build --sysbuild --domain hello_world
357 The ``--domain`` argument can be combined with the ``--target`` argument to
360 west build --sysbuild --domain hello_world --target help
363 -------------
365 See :ref:`using-snippets`.
367 .. _west-building-config:
372 You can :ref:`configure <west-config-cmd>` ``west build`` using these options.
376 .. list-table::
378 :header-rows: 1
380 * - Option
381 - Description
382 * - ``build.board``
383 - String. If given, this the board used by :ref:`west build
384 <west-building>` when ``--board`` is not given and ``BOARD``
386 * - ``build.board_warn``
387 - Boolean, default ``true``. If ``false``, disables warnings when
389 * - ``build.cmake-args``
390 - String. If present, the value will be split according to shell rules and
391 passed to CMake whenever a new build system is generated. See
392 :ref:`west-building-cmake-config`.
393 * - ``build.dir-fmt``
394 - String, default ``build``. The build folder format string, used by
398 - ``board``: The board name
399 - ``source_dir``: The relative path from the current working directory
402 - ``app``: The name of the source directory.
403 * - ``build.generator``
404 - String, default ``Ninja``. The `CMake Generator`_ to use to create a
406 :ref:`above example <west-building-generator>`)
407 * - ``build.guess-dir``
408 - String, instructs west whether to try to guess what build folder to use
409 when ``build.dir-fmt`` is in use and not enough information is available
412 - ``never`` (default): Never try to guess, bail out instead and
413 require the user to provide a build folder with ``-d``.
414 - ``runners``: Try to guess the folder when using any of the 'runner'
417 * - ``build.pristine``
418 - String. Controls the way in which ``west build`` may clean the build
421 - ``never`` (default): Never automatically make the build folder
423 - ``auto``: ``west build`` will automatically make the build folder
428 - ``always``: Always make the build folder pristine before building, if
430 * - ``build.sysbuild``
431 - Boolean, default ``false``. If ``true``, build application using the
432 sysbuild infrastructure.
434 .. _west-flashing:
439 .. tip:: Run ``west flash -h`` for additional help.
444 From a Zephyr build directory, re-build the binary and flash it to
452 To specify the build directory, use ``--build-dir`` (or ``-d``)::
454 west flash --build-dir path/to/build/directory
458 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
465 programs, you can specify which one to use using the ``--runner`` (or
466 ``-r``) option. For example, if West flashes your board with
470 west flash --runner jlink
473 ``BOARD_FLASH_RUNNER`` CMake variable, and the debug runner with
480 west build [...] -- -DBOARD_FLASH_RUNNER=jlink
482 See :ref:`west-building-cmake-args` and :ref:`west-building-cmake-config` for
483 more information on setting CMake arguments.
485 See :ref:`west-runner` below for more information on the ``runner``
487 be obtained with ``west flash -H``; if run from a build directory or
488 with ``--build-dir``, this will print additional information on
494 The CMake cache contains default values West uses while flashing, such
503 west flash --hex-file path/to/some/other.hex
505 The ``west flash -h`` output includes a complete list of overrides
508 Runner-Specific Overrides
512 example, some runners support an ``--erase`` flag, which mass-erases
516 supports, as well as their usage information, use ``--context`` (or
517 ``-H``)::
519 west flash --context
523 Note the capital H in the short option name. This re-runs the build
526 When running West outside of a build directory, ``west flash -H`` just
527 prints a list of runners. You can use ``west flash -H -r
528 <runner-name>`` to print usage information for options supported by
533 west flash -H -r jlink
535 .. _west-multi-domain-flashing:
537 Multi-domain flashing
540 When a :ref:`west-multi-domain-builds` folder is detected, then ``west flash``
541 will flash all domains in the order defined by sysbuild.
543 It is possible to flash the image from a single domain in a multi-domain project
544 by using ``--domain``.
546 For example, in a multi-domain build with :zephyr:code-sample:`hello_world` and
547 `MCUboot`_, you can use the ``--domain hello_world`` domain to only flash
550 west flash --domain hello_world
552 .. _west-debugging:
559 Run ``west debug -h`` or ``west debugserver -h`` for additional help.
577 To specify the build directory, use ``--build-dir`` (or ``-d``)::
579 west debug --build-dir path/to/build/directory
580 west debugserver --build-dir path/to/build/directory
584 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
591 programs, you can specify which one to use using the ``--runner`` (or
592 ``-r``) option. For example, if West debugs your board with
593 ``pyocd-gdbserver`` by default, but it also supports JLink, you can
596 west debug --runner jlink
597 west debugserver --runner jlink
599 See :ref:`west-runner` below for more information on the ``runner``
601 be obtained with ``west debug -H``; if run from a build directory or
602 with ``--build-dir``, this will print additional information on
608 The CMake cache contains default values West uses for debugging, such
617 west debug --elf-file path/to/some/other.elf
618 west debugserver --elf-file path/to/some/other.elf
620 The ``west debug -h`` output includes a complete list of overrides
623 Runner-Specific Overrides
631 supports, as well as their usage information, use ``--context`` (or
632 ``-H``)::
634 west debug --context
636 (The command ``west debugserver --context`` will print the same output.)
640 Note the capital H in the short option name. This re-runs the build
643 When running West outside of a build directory, ``west debug -H`` just
644 prints a list of runners. You can use ``west debug -H -r
645 <runner-name>`` to print usage information for options supported by
650 west debug -H -r jlink
652 .. _west-multi-domain-debugging:
654 Multi-domain debugging
658 :ref:`west-multi-domain-builds` folder is detected, ``west debug``
659 will debug the ``default`` domain specified by sysbuild.
664 west build --sysbuild path/to/source/directory
666 For example, when building ``hello_world`` with `MCUboot`_ using sysbuild,
669 west build --sysbuild samples/hello_world
677 west debug --domain hello_world
682 west debug --domain mcuboot
684 .. _west-runner:
690 :ref:`flash-debug-host-tools`. These wrappers are all defined in a Python
704 .. tip:: Run ``west robot -h`` for additional help.
709 Currently the command supports only one runner which is using ``renode-test``,
715 west robot --runner=renode-robot --testsuite path/to/testsuite.robot
720 To pass additional parameters to Renode use ``--renode-robot-args`` switch.
723 …west robot --runner=renode-robot --testsuite path/to/testsuite.robot --renode-robot-arg="--show-lo…
725 Runner-Specific Overrides
729 supports, as well as their usage information, use ``--context`` (or
730 ``-H``)::
732 west robot --runner=renode-robot --context
735 To view all available options "renode-test" runner supports, use::
737 west robot --runner=renode-robot --renode-robot-help
750 west simulate --runner=renode
757 west simulate --runner=renode --renode-command start
762 west simulate --runner=renode --renode-arg="--console"
765 For details on using Renode see `Renode - documentation`_.
767 .. _Renode - documentation:
770 Runner-Specific Overrides
774 as their usage information, use ``--context`` (or ``-H``)::
776 west simulate --runner=renode --context
780 west simulate --runner=renode --renode-help
828 https://cmake.org/cmake/help/latest/manual/cmake.1.html
831 https://cmake.org/cmake/help/latest/variable/CMAKE_VERBOSE_MAKEFILE.html
834 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html