Lines Matching +full:source +full:- +full:dir
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.
28 The ``build`` command helps you build Zephyr applications from source. You can
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>
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``
102 --------------------------
104 To force a CMake re-run, use the ``--cmake`` (or ``-c``) option::
106 west build -c
109 -----------------------
118 .. _west-building-dirs:
120 Setting Source and Build Directories
121 ------------------------------------
123 To set the application source directory explicitly, give its path as a
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 --------------
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.
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
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
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
400 to the source directory. If the current working directory is inside
401 the source directory this will be set to an empty string.
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``
661 The default domain will be the application given as the source directory.
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``,
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
820 e.g. as a source of symbol tables.
834 https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html