Skip to content
Permalink
Browse files

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>
  • Loading branch information...
mbolivar authored and nashif committed May 1, 2019
1 parent 88fb8ba commit 81e005f4d5174901591694ad4b5d1a75e775815a
Showing with 116 additions and 85 deletions.
  1. +113 −48 doc/guides/west/build-flash-debug.rst
  2. +3 −37 doc/guides/west/config.rst
@@ -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::

west build -b <BOARD> --build-dir path/to/build/directory
You can use the :ref:```west boards`` <west-boards>` command to list all
supported boards.

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.
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.

.. 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.
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.

.. tip::
You can use the :ref:`west boards <west-boards>` command to list all
supported boards.
To configure ``west build`` to build for the ``reel_board`` by default::

west config build.board reel_board

Specify the source directory path as the first positional argument::
(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

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``).

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::

west build -t clean
west build -b qemu_x86 -t run samples/hello_world

You can list all targets with ``ninja help`` (or ``west build -t help``) inside
the build folder.
As another example, to use ``-t`` to list all build system targets::

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::
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::

You can run ``west config build.pristine auto`` to make this setting
permanent.

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 samples/hello_world -- -G'Unix Makefiles'
west build -b reel_board -- -G'Unix Makefiles'

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::
.. 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.

0 comments on commit 81e005f

Please sign in to comment.
You can’t perform that action at this time.