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,
73 Here are some ``west build`` usage examples, grouped by area.
76 --------------------------
78 To force a CMake re-run, use the ``--cmake`` (or ``--c``) option::
80 west build -c
83 -----------------------
85 To configure ``west build`` to build for the ``reel_board`` by default::
87 west config build.board reel_board
92 .. _west-building-dirs:
95 ------------------------------------
100 west build -b <BOARD> path/to/source/directory
102 To set the build directory explicitly, use ``--build-dir`` (or ``-d``)::
104 west build -b <BOARD> --build-dir path/to/build/directory
107 ``build.dir-fmt`` configuration option. This lets you name build
110 west config build.dir-fmt "build/{board}/{app}"
112 With the above, running ``west build -b reel_board samples/hello_world`` will
114 :ref:`west-building-config` for more details on this option.
117 -------------------------------
119 To specify the build system target to run, use ``--target`` (or ``-t``).
125 west build -b qemu_x86 -t run samples/hello_world
127 As another example, to use ``-t`` to list all build system targets::
129 west build -t help
131 As a final example, to use ``-t`` to run the ``pristine`` target, which deletes
134 west build -t pristine
136 .. _west-building-pristine:
139 ---------------
144 To force ``west build`` make the build directory pristine before re-running
145 CMake to generate a build system, use the ``--pristine=always`` (or
146 ``-p=always``) option.
148 Giving ``--pristine`` or ``-p`` without a value has the same effect as giving
149 it the value ``always``. For example, these commands are equivalent::
151 west build -p -b reel_board samples/hello_world
152 west build -p=always -b reel_board samples/hello_world
154 By default, ``west build`` applies a heuristic to detect if the build directory
155 needs to be made pristine. This is the same as using ``--pristine=auto``.
159 You can run ``west config build.pristine always`` to always do a pristine
160 build, or ``west config build.pristine never`` to disable the heuristic.
161 See the ``west build`` :ref:`west-building-config` for details.
163 .. _west-building-verbose:
166 --------------
168 To print the CMake and compiler commands run by ``west build``, use the global
169 west verbosity option, ``-v``::
171 west -v build -b reel_board samples/hello_world
173 .. _west-building-generator:
174 .. _west-building-cmake-args:
176 One-Time CMake Arguments
177 ------------------------
179 To pass additional arguments to the CMake invocation performed by ``west
180 build``, pass them after a ``--`` at the end of the command line.
184 Passing additional CMake arguments like this forces ``west build`` to re-run
187 After using ``--`` once to generate the build directory, use ``west build -d
188 <build-dir>`` on subsequent runs to do incremental builds.
191 ``west build`` uses by default), run::
193 west build -b reel_board -- -G'Unix Makefiles'
197 west build -b reel_board -- -G'Unix Makefiles' -DCMAKE_VERBOSE_MAKEFILE=ON
199 Notice how the ``--`` only appears once, even though multiple CMake arguments
200 are given. All command-line arguments to ``west build`` after a ``--`` are
203 .. _west-building-dtc-overlay-file:
205 To set :ref:`DTC_OVERLAY_FILE <important-build-vars>` to
206 :file:`enable-modem.overlay`, using that file as a
207 :ref:`devicetree overlay <dt-guide>`::
209 west build -b reel_board -- -DDTC_OVERLAY_FILE=enable-modem.overlay
214 west build -- -DOVERLAY_CONFIG=file.conf
216 .. _west-building-cmake-config:
219 -------------------------
221 The previous section describes how to add CMake arguments for a single ``west
222 build`` command. If you want to save CMake arguments for ``west build`` to use
224 ``build.cmake-args`` configuration option. Whenever ``west build`` runs CMake
228 Remember that, by default, ``west build`` **tries to avoid generating a new
231 <west-building-pristine>` after setting ``build.cmake-args`` to make sure it
237 west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
239 (The extra ``--`` is used to force the rest of the command to be treated as a
240 positional argument. Without it, :ref:`west config <west-config-cmd>` would
241 treat the ``-DVAR=VAL`` syntax as a use of its ``-D`` option.)
246 west config build.cmake-args -- -DCMAKE_VERBOSE_MAKEFILE=ON
248 To save more than one argument in ``build.cmake-args``, use a single string
249 whose value can be split into distinct arguments (``west build`` uses the
257 west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_VERBOSE_MAKEFILE=ON"
260 combine CMake's ``-C <initial-cache>`` option with ``build.cmake-args``. For
262 create a file named :file:`~/my-cache.cmake` with the following contents:
264 .. code-block:: cmake
271 west config build.cmake-args "-C ~/my-cache.cmake"
283 --------------------
285 Use ``-o`` to pass options to the underlying build tool.
287 This works with both ``ninja`` (:ref:`the default <west-building-generator>`)
290 For example, to pass ``-dexplain`` to ``ninja``::
292 west build -o=-dexplain
294 As another example, to pass ``--keep-going`` to ``make``::
296 west build -o=--keep-going
298 Note that using ``-o=--foo`` instead of ``-o --foo`` is required to prevent
299 ``--foo`` from being treated as a ``west build`` option.
302 -----------------
305 one. You can control this explicitly with the ``-j`` option supported by both
310 west build -o=-j4
312 The ``-o`` option is described further in the previous section.
314 .. _west-building-config:
319 You can :ref:`configure <west-config-cmd>` ``west build`` using these options.
323 .. list-table::
325 :header-rows: 1
327 * - Option
328 - Description
329 * - ``build.board``
330 - String. If given, this the board used by :ref:`west build
331 <west-building>` when ``--board`` is not given and :envvar:`BOARD`
333 * - ``build.board_warn``
334 - Boolean, default ``true``. If ``false``, disables warnings when
335 ``west build`` can't figure out the target board.
336 * - ``build.cmake-args``
337 - String. If present, the value will be split according to shell rules and
339 :ref:`west-building-cmake-config`.
340 * - ``build.dir-fmt``
341 - String, default ``build``. The build folder format string, used by
342 west whenever it needs to create or locate a build folder. The currently
345 - ``board``: The board name
346 - ``source_dir``: The relative path from the current working directory
349 - ``app``: The name of the source directory.
350 * - ``build.generator``
351 - String, default ``Ninja``. The `CMake Generator`_ to use to create a
353 :ref:`above example <west-building-generator>`)
354 * - ``build.guess-dir``
355 - String, instructs west whether to try to guess what build folder to use
356 when ``build.dir-fmt`` is in use and not enough information is available
359 - ``never`` (default): Never try to guess, bail out instead and
360 require the user to provide a build folder with ``-d``.
361 - ``runners``: Try to guess the folder when using any of the 'runner'
362 commands. These are typically all commands that invoke an external
364 * - ``build.pristine``
365 - String. Controls the way in which ``west build`` may clean the build
368 - ``never`` (default): Never automatically make the build folder
370 - ``auto``: ``west build`` will automatically make the build folder
375 - ``always``: Always make the build folder pristine before building, if
378 .. _west-flashing:
380 Flashing: ``west flash``
383 .. tip:: Run ``west flash -h`` for additional help.
388 From a Zephyr build directory, re-build the binary and flash it to
391 west flash
396 To specify the build directory, use ``--build-dir`` (or ``-d``)::
398 west flash --build-dir path/to/build/directory
400 If you don't specify the build directory, ``west flash`` searches for one in
402 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
409 programs, you can specify which one to use using the ``--runner`` (or
410 ``-r``) option. For example, if West flashes your board with
414 west flash --runner jlink
424 west build [...] -- -DBOARD_FLASH_RUNNER=jlink
426 See :ref:`west-building-cmake-args` and :ref:`west-building-cmake-config` for
429 See :ref:`west-runner` below for more information on the ``runner``
430 library used by West. The list of runners which support flashing can
431 be obtained with ``west flash -H``; if run from a build directory or
432 with ``--build-dir``, this will print additional information on
438 The CMake cache contains default values West uses while flashing, such
447 west flash --hex-file path/to/some/other.hex
449 The ``west flash -h`` output includes a complete list of overrides
452 Runner-Specific Overrides
456 example, some runners support an ``--erase`` flag, which mass-erases
460 supports, as well as their usage information, use ``--context`` (or
461 ``-H``)::
463 west flash --context
467 Note the capital H in the short option name. This re-runs the build
470 When running West outside of a build directory, ``west flash -H`` just
471 prints a list of runners. You can use ``west flash -H -r
472 <runner-name>`` to print usage information for options supported by
477 west flash -H -r jlink
479 .. _west-debugging:
481 Debugging: ``west debug``, ``west debugserver``
486 Run ``west debug -h`` or ``west debugserver -h`` for additional help.
494 west debug
499 west debugserver
504 To specify the build directory, use ``--build-dir`` (or ``-d``)::
506 west debug --build-dir path/to/build/directory
507 west debugserver --build-dir path/to/build/directory
509 If you don't specify the build directory, these commands search for one in
511 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
518 programs, you can specify which one to use using the ``--runner`` (or
519 ``-r``) option. For example, if West debugs your board with
520 ``pyocd-gdbserver`` by default, but it also supports JLink, you can
523 west debug --runner jlink
524 west debugserver --runner jlink
526 See :ref:`west-runner` below for more information on the ``runner``
527 library used by West. The list of runners which support debugging can
528 be obtained with ``west debug -H``; if run from a build directory or
529 with ``--build-dir``, this will print additional information on
535 The CMake cache contains default values West uses for debugging, such
544 west debug --elf-file path/to/some/other.elf
545 west debugserver --elf-file path/to/some/other.elf
547 The ``west debug -h`` output includes a complete list of overrides
550 Runner-Specific Overrides
558 supports, as well as their usage information, use ``--context`` (or
559 ``-H``)::
561 west debug --context
563 (The command ``west debugserver --context`` will print the same output.)
567 Note the capital H in the short option name. This re-runs the build
570 When running West outside of a build directory, ``west debug -H`` just
571 prints a list of runners. You can use ``west debug -H -r
572 <runner-name>`` to print usage information for options supported by
577 west debug -H -r jlink
579 .. _west-runner:
584 The flash and debug commands use Python wrappers around various
585 :ref:`flash-debug-host-tools`. These wrappers are all defined in a Python
600 flash and debug commands. This is the core abstraction used to implement
606 to implement multiple extension commands than a stable API.
628 If you prefer not to use West to flash or debug your board, simply
636 By default, these West commands rebuild binaries before flashing and
639 commands do it).
650 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html