doc: re-word and extend west build documentation
Try to make the language simpler. Introduce each example with a paragraph that says "To <DO XYZ>" to make them easier to find. Move the config options to the documentation for that command to make them easier to find. Add some more examples for use cases we've gotten questions about. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Marti Bolivar
Anas Nashif
parent
88fb8bacfb
commit
81e005f4d5
2 changed files with 118 additions and 87 deletions
|
|
@ -29,86 +29,151 @@ Building: ``west build``
|
|||
|
||||
.. tip:: Run ``west build -h`` for additional help.
|
||||
|
||||
The ``build`` command allows you to build any source tree from any directory
|
||||
in your file system, placing the build results in a folder of your choice.
|
||||
The ``build`` command helps you build Zephyr applications from source. You can
|
||||
use :ref:`west config <west-config-cmd>` to configure its behavior.
|
||||
|
||||
In its simplest form, the command can be run by navigating to the root folder
|
||||
(i.e. the folder containing a :file:`CMakeLists.txt` file) of the Zephyr
|
||||
application of your choice and running::
|
||||
Basics
|
||||
======
|
||||
|
||||
The easiest way to use it is to go to an application's root directory (i.e. the
|
||||
folder containing its :file:`CMakeLists.txt`) and then run::
|
||||
|
||||
west build -b <BOARD>
|
||||
|
||||
Where ``<BOARD>`` is the name of the board you want to build for. This is
|
||||
exactly the same name you would supply to CMake if you were to invoke it with:
|
||||
``cmake -DBOARD=<BOARD>``.
|
||||
A build folder named :file:`build` (default name) will be created and the
|
||||
build output will be placed in it.
|
||||
|
||||
To specify the build directory, use ``--build-dir`` (or ``-d``)::
|
||||
.. tip::
|
||||
|
||||
You can use the :ref:```west boards`` <west-boards>` command to list all
|
||||
supported boards.
|
||||
|
||||
A build directory named :file:`build` will be created, and the application will
|
||||
be compiled there after ``west build`` runs CMake to create a build system in
|
||||
that directory. If you run ``west build`` with an existing build directory, the
|
||||
application is incrementally re-compiled without re-running CMake.
|
||||
|
||||
You don't need to give ``-b`` if you've already got an existing build
|
||||
directory; ``west build`` can figure out the board from the CMake cache. For
|
||||
new builds, the :envvar:`BOARD` environment variable and ``build.board``
|
||||
configuration option can also be used to set the board.
|
||||
|
||||
To configure ``west build`` to build for the ``reel_board`` by default::
|
||||
|
||||
west config build.board reel_board
|
||||
|
||||
(You can use any other board supported by Zephyr here; it doesn't have to be
|
||||
``reel_board``.)
|
||||
|
||||
To use another build directory, use ``--build-dir`` (or ``-d``)::
|
||||
|
||||
west build -b <BOARD> --build-dir path/to/build/directory
|
||||
|
||||
Since the build directory defaults to :file:`build`, if you do not specify
|
||||
a build directory but a folder named :file:`build` is present, that will be used,
|
||||
allowing you to incrementally build from outside the :file:`build` folder with
|
||||
no additional parameters.
|
||||
|
||||
.. note::
|
||||
The ``-b <BOARD>`` parameter is only required when there is no CMake cache
|
||||
present at all, usually when you are building from scratch or creating a
|
||||
brand new build directory. After that you can rebuild (even with additional
|
||||
parameters) without having to specify the board again. If you're unsure
|
||||
whether ``-b`` is required, just try leaving it out. West will print an
|
||||
error if the option is required and was not given.
|
||||
|
||||
.. tip::
|
||||
You can use the :ref:`west boards <west-boards>` command to list all
|
||||
supported boards.
|
||||
|
||||
Specify the source directory path as the first positional argument::
|
||||
To specify the application source directory explicitly, give its path as a
|
||||
positional argument::
|
||||
|
||||
west build -b <BOARD> path/to/source/directory
|
||||
|
||||
Additionally you can specify the build system target using the ``--target``
|
||||
(or ``-t``) option. For example, to run the ``clean`` target::
|
||||
To specify the build system target to run, use ``--target`` (or ``-t``).
|
||||
|
||||
west build -t clean
|
||||
For example, on host platforms with QEMU, you can use the ``run`` target to
|
||||
build and run the :ref:`hello_world` sample for the emulated :ref:`qemu_x86
|
||||
<qemu_x86>` board in one command::
|
||||
|
||||
You can list all targets with ``ninja help`` (or ``west build -t help``) inside
|
||||
the build folder.
|
||||
west build -b qemu_x86 -t run samples/hello_world
|
||||
|
||||
A clean build can be triggered by using the ``--pristine`` (or ``-p``) option.
|
||||
This is particularly handy if you want to switch source dirs or boards without
|
||||
using a different build dir::
|
||||
As another example, to use ``-t`` to list all build system targets::
|
||||
|
||||
west build -t help
|
||||
|
||||
As a final example, to use ``-t`` to run the ``pristine`` target, which deletes
|
||||
all the files in the build directory::
|
||||
|
||||
west build -t pristine
|
||||
|
||||
To have ``west build`` run the ``pristine`` target before re-running CMake to
|
||||
generate a build system, use the ``--pristine`` (or ``-p``) option. For
|
||||
example, to switch board and application (which requires a pristine build
|
||||
directory) in one command::
|
||||
|
||||
west build -b qemu_x86 samples/philosophers
|
||||
west build -p -b reel_board samples/hello_world
|
||||
|
||||
If you are unsure about whether the command-line parameters you supply to
|
||||
``west build`` require a clean build you can let west decide for you by using
|
||||
the ``auto`` setting in the ``--pristine`` option::
|
||||
To let west decide for you if a pristine build is needed, use ``-p auto``::
|
||||
|
||||
west build -p auto -b reel_board samples/hello_world
|
||||
|
||||
Finally, you can add additional arguments to the CMake invocation performed by
|
||||
``west build`` by supplying additional parameters (after a ``--``) to the
|
||||
command. For example, to use the Unix Makefiles CMake generator instead of
|
||||
Ninja (which ``west build`` uses by default), run::
|
||||
.. tip::
|
||||
|
||||
west build -b reel_board samples/hello_world -- -G'Unix Makefiles'
|
||||
You can run ``west config build.pristine auto`` to make this setting
|
||||
permanent.
|
||||
|
||||
As another example, and assuming you have already built a sample, the following
|
||||
command adds the ``file.conf`` Kconfig fragment to the files which are merged
|
||||
into your final build configuration::
|
||||
To add additional arguments to the CMake invocation performed by ``west
|
||||
build``, pass them after a ``--`` at the end of the command line.
|
||||
|
||||
For example, to use the Unix Makefiles CMake generator instead of Ninja (which
|
||||
``west build`` uses by default), run::
|
||||
|
||||
west build -b reel_board -- -G'Unix Makefiles'
|
||||
|
||||
.. note::
|
||||
|
||||
Passing additional CMake arguments like this forces ``west build`` to re-run
|
||||
CMake, even if a build system has already been generated.
|
||||
|
||||
As another example, to use Unix Makefiles and enable the
|
||||
`CMAKE_VERBOSE_MAKEFILE`_ option::
|
||||
|
||||
west build -b reel_board -- -G'Unix Makefiles' -DCMAKE_VERBOSE_MAKEFILE=ON
|
||||
|
||||
Notice how the ``--`` only appears once, even though multiple CMake arguments
|
||||
are given. All command-line arguments to ``west build`` after a ``--`` are
|
||||
passed to CMake.
|
||||
|
||||
As a final example, to merge the :file:`file.conf` Kconfig fragment into your
|
||||
build's :file:`.config`::
|
||||
|
||||
west build -- -DOVERLAY_CONFIG=file.conf
|
||||
|
||||
Passing additional CMake arguments like this forces ``west build`` to re-run
|
||||
CMake, even if a build system has already been generated. You can also force
|
||||
a CMake re-run using the ``-c`` (or ``--cmake``) option::
|
||||
To force a CMake re-run, use the ``--cmake`` (or ``--c``) option::
|
||||
|
||||
west build -c
|
||||
|
||||
Configuration Options
|
||||
=====================
|
||||
|
||||
You can :ref:`configure <west-config-cmd>` ``west build`` using these options.
|
||||
|
||||
.. NOTE: docs authors: keep this table sorted alphabetically
|
||||
|
||||
.. list-table::
|
||||
:widths: 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Option
|
||||
- Description
|
||||
* - ``build.board``
|
||||
- String. If given, this the board used by :ref:`west build
|
||||
<west-building>` when ``--board`` is not given and :envvar:`BOARD`
|
||||
is unset in the environment.
|
||||
* - ``build.board_warn``
|
||||
- Boolean, default ``true``. If ``false``, disables warnings when
|
||||
``west build`` can't figure out the target board.
|
||||
* - ``build.pristine``
|
||||
- String. Controls the way in which ``west build`` may clean the build
|
||||
folder before building. Can take the following values:
|
||||
|
||||
- ``never`` (default): Never automatically make the build folder
|
||||
pristine.
|
||||
- ``auto``: ``west build`` will automatically make the build folder
|
||||
pristine before building, if a build system is present and the build
|
||||
would fail otherwise (e.g. the user has specified a different board
|
||||
or application from the one previously used to make the build
|
||||
directory).
|
||||
- ``always``: Always make the build folder pristine before building, if
|
||||
a build system is present.
|
||||
|
||||
.. _west-flashing:
|
||||
|
||||
Flashing: ``west flash``
|
||||
|
|
@ -376,5 +441,5 @@ commands do it).
|
|||
.. _cmake(1):
|
||||
https://cmake.org/cmake/help/latest/manual/cmake.1.html
|
||||
|
||||
.. _namespace package:
|
||||
https://www.python.org/dev/peps/pep-0420/
|
||||
.. _CMAKE_VERBOSE_MAKEFILE:
|
||||
https://cmake.org/cmake/help/latest/variable/CMAKE_VERBOSE_MAKEFILE.html
|
||||
|
|
|
|||
|
|
@ -118,8 +118,9 @@ To undo the above change:
|
|||
Built-in Configuration Options
|
||||
------------------------------
|
||||
|
||||
The following table documents configuration options supported by west's built-in
|
||||
commands.
|
||||
The following table documents configuration options supported by west's
|
||||
built-in commands. Configuration options supported by Zephyr's extension
|
||||
commands are documented in the pages for those commands.
|
||||
|
||||
.. NOTE: docs authors: keep this table sorted by section, then option.
|
||||
|
||||
|
|
@ -150,38 +151,3 @@ commands.
|
|||
environment overrides the value of the ``zephyr.base`` configuration
|
||||
option. If set to ``"configfile"``, the configuration option wins
|
||||
instead.
|
||||
|
||||
Zephyr Extension Commands Configuration Options
|
||||
-----------------------------------------------
|
||||
|
||||
The following table documents configuration options supported by zephyr's
|
||||
extension commands (found in :file:`scripts/west_commands`).
|
||||
|
||||
.. NOTE: docs authors: keep this table sorted by section, then option.
|
||||
|
||||
.. list-table::
|
||||
:widths: 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Option
|
||||
- Description
|
||||
* - ``build.board``
|
||||
- String. If given, this the board used by :ref:`west build
|
||||
<west-building>` when ``--board`` is not given and :envvar:`BOARD`
|
||||
is unset in the environment.
|
||||
* - ``build.board_warn``
|
||||
- Boolean, default ``true``. If ``false``, disables warnings when
|
||||
``west build`` can't figure out the target board.
|
||||
* - ``build.pristine``
|
||||
- String. Controls the way in which ``west build`` may clean the build
|
||||
folder before building. Can take the following values:
|
||||
|
||||
- ``never`` (default): Never automatically make the build folder
|
||||
pristine.
|
||||
- ``auto``: ``west build`` will automatically make the build folder
|
||||
pristine before building, if a build system is present and the build
|
||||
would fail otherwise (e.g. the user has specified a different board
|
||||
or application from the one previously used to make the build
|
||||
directory).
|
||||
- ``always``: Always make the build folder pristine before building, if
|
||||
a build system is present.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue