Lines Matching +full:- +full:- +full:run +full:- +full:attempt
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
35 run ``west build`` from a Zephyr build directory.
37 - Otherwise, if you run ``west build`` from a Zephyr application's source
46 and then run::
48 west build -b <BOARD>
52 ``cmake -DBOARD=<BOARD>``.
56 You can use the :ref:`west boards <west-boards>` command to list all
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
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
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
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``).
147 For example, on host platforms with QEMU, you can use the ``run`` target to
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
180 By default, ``west build`` makes no attempt to detect if the build directory
182 try to reuse a build directory for a different ``--board``.
184 Using ``--pristine=auto`` makes ``west build`` detect some of these situations
189 You can run ``west config build.pristine always`` to always do a pristine
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 ------------------------
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
219 After using ``--`` once to generate the build directory, use ``west build -d
220 <build-dir>`` on subsequent runs to do incremental builds.
226 ``west build`` uses by default), run::
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
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:
254 -------------------------
259 ``build.cmake-args`` configuration option. Whenever ``west build`` runs CMake
266 <west-building-pristine>` after setting ``build.cmake-args`` to make sure it
270 run::
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.)
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"
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
304 Then run::
306 west config build.cmake-args "-C ~/my-cache.cmake"
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
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
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
480 west build [...] -- -DBOARD_FLASH_RUNNER=jlink
482 See :ref:`west-building-cmake-args` and :ref:`west-building-cmake-config` for
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
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``
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
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``
664 west build --sysbuild path/to/source/directory
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``,
713 From a Zephyr build directory, to run a Robot test suite::
715 west robot --runner=renode-robot --testsuite path/to/testsuite.robot
717 This will run all tests from testsuite.robot and print output provided
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
748 From a Zephyr build directory, to run the built binary::
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
834 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html