Lines Matching +full:run +full:- +full:in +full:- +full:debug
1 .. _west-build-flash-debug:
6 Zephyr provides several :ref:`west extension commands <west-extensions>` for
8 ``build``, ``flash``, ``debug``, ``debugserver`` and ``attach``.
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
14 deeply enough that it doesn't have any subheadings in the main nav.
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
39 application is compiled in it.
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
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
67 For new builds, the ``--board`` option, :envvar:`BOARD` environment variable,
68 or ``build.board`` configuration option are checked (in that order).
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
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
149 :zephyr:board:`qemu_x86 <qemu_x86>` board in one command::
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
158 all the files in the build directory::
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
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.
222 Alternatively, make your CMake arguments permanent as described in the next
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
261 rules and includes the results in the ``cmake`` command line.
264 build system if one is present** in your build directory. Therefore, you need
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"
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
296 instance, another way to set the options used in the previous example is to
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``
385 is unset in the environment.
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'
416 tool, such as ``flash`` and ``debug``.
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
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
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
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
496 zephyr binaries to flash in several formats, and more. You can
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
524 in order to ensure the information displayed is up to date!
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:
554 Debugging: ``west debug``, ``west debugserver``
559 Run ``west debug -h`` or ``west debugserver -h`` for additional help.
565 open up a debug console (e.g. a GDB session)::
567 west debug
574 Without options, the behavior is the same as ``ninja debug`` and
575 ``ninja debugserver`` (or ``make debug``, etc.).
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
585 debug`` searches there instead of :file:`build`.
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
615 other debug configuration at default values::
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
628 ports used by debug servers.
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
641 in order to ensure the information displayed is up to date!
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``
659 will debug the ``default`` domain specified by sysbuild.
664 west build --sysbuild path/to/source/directory
669 west build --sysbuild samples/hello_world
671 So to debug ``hello_world`` you can do::
673 west debug
677 west debug --domain hello_world
679 If you wish to debug MCUboot, you must explicitly specify MCUboot as the domain
680 to debug::
682 west debug --domain mcuboot
684 .. _west-runner:
686 Flash and debug runners
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
692 called a *runner*. Runners can flash and/or debug Zephyr programs.
697 ``ZephyrBinaryRunner`` is available in the ``runners.core`` module; individual
698 runner implementations are in other submodules, such as ``runners.nrfjprog``,
704 .. tip:: Run ``west robot -h`` for additional help.
709 Currently the command supports only one runner which is using ``renode-test``,
710 (essentially a wrapper for running Robot tests in Renode), but can be
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.
721 For example to show Renode logs in addition to Robot Framework's output:
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
754 then can be started by typing "start" or "s" in Renode's Monitor. This can also be
757 west simulate --runner=renode --renode-command start
759 To pass an argument to Renode itself, for example to start Renode in console mode
762 west simulate --runner=renode --renode-arg="--console"
764 From that point on Renode can be used normally in both console and window modes.
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
794 Developers can add support for new ways to flash and debug Zephyr programs by
801 The test cases in :zephyr_file:`scripts/west_commands/tests` add unit test
814 If you prefer not to use West to flash or debug your board, simply
824 targets provided by Zephyr's build system (in fact, that's how these
834 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html