Lines Matching +full:west +full:- +full:commands
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:
23 Building: ``west build``
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
44 The easiest way to use ``west build`` is to go to an application's root
48 west build -b <BOARD>
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
61 that directory. If ``west build`` finds an existing build directory, the
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
79 ``west build`` to build multiple domains.
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
93 A single domain from a multi-domain project can be built by using ``--domain``
99 Here are some ``west build`` usage examples, grouped by area.
102 --------------------------
104 To force a CMake re-run, use the ``--cmake`` (or ``-c``) option::
106 west build -c
109 -----------------------
111 To configure ``west build`` to build for the ``reel_board`` by default::
113 west config build.board reel_board
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
175 it the value ``always``. For example, these commands are equivalent::
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
190 build, or ``west config build.pristine never`` to disable the heuristic.
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
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 -------------------------
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
263 Remember that, by default, ``west build`` **tries to avoid generating a new
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.)
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
284 whose value can be split into distinct arguments (``west build`` uses the
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
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
388 ``west build`` can't figure out the target board.
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
395 west whenever it needs to create or locate a build folder. The currently
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'
415 commands. These are typically all commands that invoke an external
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:
436 Flashing: ``west flash``
439 .. tip:: Run ``west flash -h`` for additional help.
444 From a Zephyr build directory, re-build the binary and flash it to
447 west flash
452 To specify the build directory, use ``--build-dir`` (or ``-d``)::
454 west flash --build-dir path/to/build/directory
456 If you don't specify the build directory, ``west flash`` searches for one in
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``
486 library used by West. The list of runners which support flashing can
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``
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:
554 Debugging: ``west debug``, ``west debugserver``
559 Run ``west debug -h`` or ``west debugserver -h`` for additional help.
567 west debug
572 west debugserver
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
582 If you don't specify the build directory, these commands search for one in
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``
600 library used by West. The list of runners which support debugging can
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
657 ``west debug`` can only debug a single domain at a time. When a
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
673 west debug
677 west debug --domain hello_world
682 west debug --domain mcuboot
684 .. _west-runner:
689 The flash and debug commands use Python wrappers around various
690 :ref:`flash-debug-host-tools`. These wrappers are all defined in a Python
701 Running Robot Framework tests: ``west robot``
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
739 Simulating a board with: ``west simulate``
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
786 flash and debug commands. This is the core abstraction used to implement
792 to implement multiple extension commands than a stable API.
814 If you prefer not to use West to flash or debug your board, simply
822 By default, these West commands rebuild binaries before flashing and
825 commands do it).
834 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html