Lines Matching full:build
1 .. _west-build-flash-debug:
8 ``build``, ``flash``, ``debug``, ``debugserver`` and ``attach``.
23 Building: ``west build``
26 .. tip:: Run ``west build -h`` for a quick overview.
28 The ``build`` command helps you build Zephyr applications from source. You can
33 - If there is a Zephyr build directory named :file:`build` in your current
35 run ``west build`` from a Zephyr build directory.
37 - Otherwise, if you run ``west build`` from a Zephyr application's source
38 directory and no build directory is found, a new one is created and the
44 The easiest way to use ``west build`` is to go to an application's root
48 west build -b <BOARD>
50 Where ``<BOARD>`` is the name of the board you want to build for. This is
59 A build directory named :file:`build` will be created, and the application will
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
66 build directory; ``west build`` can figure out the board from the CMake cache.
68 or ``build.board`` configuration option are checked (in that order).
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.
86 The ``build.sysbuild`` configuration option can be enabled to tell
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
99 Here are some ``west build`` usage examples, grouped by area.
106 west build -c
111 To configure ``west build`` to build for the ``reel_board`` by default::
113 west config build.board reel_board
120 Setting Source and Build Directories
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
132 To change the default build directory from :file:`build`, use the
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
139 use build directory :file:`build/reel_board/hello_world`. See
142 Setting the Build System Target
145 To specify the build system target to run, use ``--target`` (or ``-t``).
148 build and run the :ref:`hello_world` sample for the emulated :ref:`qemu_x86
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
158 all the files in the build directory::
160 west build -t pristine
167 A *pristine* build directory is essentially a new build directory. All
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
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
185 and make the build directory pristine before trying the build.
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.
198 To print the CMake and compiler commands run by ``west build``, use the global
201 west -v build -b reel_board samples/hello_world
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
215 the CMake build configuration step, even if a build system has already been
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
235 are given. All command-line arguments to ``west build`` after a ``--`` are
240 To set :ref:`DTC_OVERLAY_FILE <important-build-vars>` to
244 west build -b reel_board -- -DDTC_OVERLAY_FILE=enable-modem.overlay
246 To merge the :file:`file.conf` Kconfig fragment into your build's
249 west build -- -DEXTRA_CONF_FILE=file.conf
257 build`` command. If you want to save CMake arguments for ``west build`` to use
258 every time it generates a new build system instead, you should use the
259 ``build.cmake-args`` configuration option. Whenever ``west build`` runs CMake
260 to generate a build system, it splits this option's value according to shell
263 Remember that, by default, ``west build`` **tries to avoid generating a new
264 build system if one is present** in your build directory. Therefore, you need
265 to either delete any existing build directories or do a :ref:`pristine build
266 <west-building-pristine>` after setting ``build.cmake-args`` to make sure it
272 west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
279 build system::
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
306 west config build.cmake-args "-C ~/my-cache.cmake"
317 Build tool arguments
320 Use ``-o`` to pass options to the underlying build tool.
323 and ``make`` based build systems.
327 west build -o=-dexplain
331 west build -o=--keep-going
334 ``--foo`` from being treated as a ``west build`` option.
336 Build parallelism
339 By default, ``ninja`` uses all of your cores to build, while ``make`` uses only
343 For example, to build with 4 cores::
345 west build -o=-j4
349 Build a single domain
352 In a multi-domain build with :ref:`hello_world` and `MCUboot`_, you can use
353 ``--domain hello_world`` to only build this domain::
355 west build --sysbuild --domain hello_world
358 build the specific target for the target, for example::
360 west build --sysbuild --domain hello_world --target help
372 You can :ref:`configure <west-config-cmd>` ``west build`` using these options.
382 * - ``build.board``
383 - String. If given, this the board used by :ref:`west build
386 * - ``build.board_warn``
388 ``west build`` can't figure out the target board.
389 * - ``build.cmake-args``
391 passed to CMake whenever a new build system is generated. See
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
403 * - ``build.generator``
405 build system. (To set a generator for a single build, see the
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
410 to resolve the build folder name. Can take these values:
413 require the user to provide a build folder with ``-d``.
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
424 pristine before building, if a build system is present and the build
426 or application from the one previously used to make the build
428 - ``always``: Always make the build folder pristine before building, if
429 a build system is present.
430 * - ``build.sysbuild``
431 - Boolean, default ``false``. If ``true``, build application using the
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
457 :file:`build`, then the current working directory. If you set the
458 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
459 flash`` searches there instead of :file:`build`.
472 You can override the default flash runner at build time by using the
480 west build [...] -- -DBOARD_FLASH_RUNNER=jlink
487 be obtained with ``west flash -H``; if run from a build directory or
488 with ``--build-dir``, this will print additional information on
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
546 For example, in a multi-domain build with :ref:`hello_world` and
564 From a Zephyr build directory, to attach a debugger to your board and
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
583 :file:`build`, then the current working directory. If you set the
584 ``build.dir-fmt`` configuration option (see :ref:`west-building-dirs`), ``west
585 debug`` searches there instead of :file:`build`.
601 be obtained with ``west debug -H``; if run from a build directory or
602 with ``--build-dir``, this will print additional information on
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
664 west build --sysbuild path/to/source/directory
669 west build --sysbuild samples/hello_world
713 From a Zephyr build directory, to run a Robot test suite::
748 From a Zephyr build directory, to run the built binary::
815 inspect the build directory for the binaries output by the build
817 ``zephyr/zephyr.hex``, etc., depending on your board's build system
824 targets provided by Zephyr's build system (in fact, that's how these