scripts: add new west build "build.cmake-args" config option

This option, if set, will add arguments to CMake whenever a new build
system is being generated.

It doesn't affect other invocations of CMake, such as when cmake(1) is
run in build tool mode to actually compile the application.

See the documentation changes for details.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2019-12-09 11:05:11 -08:00 committed by Carles Cufí
commit 0186eade51
2 changed files with 89 additions and 2 deletions

View file

@ -137,6 +137,8 @@ all the files in the build directory::
west build -t pristine
.. _west-building-pristine:
Pristine Builds
---------------
@ -160,11 +162,21 @@ To let west decide for you if a pristine build is needed, use ``-p auto``::
You can run ``west config build.pristine auto`` to make this setting
permanent.
.. _west-building-verbose:
Verbose Builds
--------------
To print the CMake and compiler commands run by ``west build``, use the global
west verbosity option, ``-v``::
west -v build -b reel_board samples/hello_world
.. _west-building-generator:
.. _west-building-cmake-args:
Additional CMake Arguments
--------------------------
One-Time CMake Arguments
------------------------
To pass additional arguments to the CMake invocation performed by ``west
build``, pass them after a ``--`` at the end of the command line.
@ -200,6 +212,72 @@ To merge the :file:`file.conf` Kconfig fragment into your build's
west build -- -DOVERLAY_CONFIG=file.conf
.. _west-building-cmake-config:
Permanent CMake Arguments
-------------------------
The previous section describes how to add CMake arguments for a single ``west
build`` command. If you want to save CMake arguments for ``west build`` to use
every time it generates a new build system instead, you should use the
``build.cmake-args`` configuration option. Whenever ``west build`` runs CMake
to generate a build system, it splits this option's value according to shell
rules and includes the results in the ``cmake`` command line.
Remember that, by default, ``west build`` **tries to avoid generating a new
build system if one is present** in your build directory. Therefore, you need
to either delete any existing build directories or do a :ref:`pristine build
<west-building-pristine>` after setting ``build.cmake-args`` to make sure it
will take effect.
For example, to always enable :makevar:`CMAKE_EXPORT_COMPILE_COMMANDS`, you can
run::
west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
(The extra ``--`` is used to force the rest of the command to be treated as a
positional argument. Without it, :ref:`west config <west-config-cmd>` would
treat the ``-DVAR=VAL`` syntax as a use of its ``-D`` option.)
To enable :makevar:`CMAKE_VERBOSE_MAKEFILE`, so CMake always produces a verbose
build system::
west config build.cmake-args -- -DCMAKE_VERBOSE_MAKEFILE=ON
To save more than one argument in ``build.cmake-args``, use a single string
whose value can be split into distinct arguments (``west build`` uses the
Python function `shlex.split()`_ internally to split the value).
.. _shlex.split(): https://docs.python.org/3/library/shlex.html#shlex.split
For example, to enable both :makevar:`CMAKE_EXPORT_COMPILE_COMMANDS` and
:makevar:`CMAKE_VERBOSE_MAKEFILE`::
west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_VERBOSE_MAKEFILE=ON"
If you want to save your CMake arguments in a separate file instead, you can
combine CMake's ``-C <initial-cache>`` option with ``build.cmake-args``. For
instance, another way to set the options used in the previous example is to
create a file named :file:`~/my-cache.cmake` with the following contents:
.. code-block:: cmake
set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "")
set(CMAKE_VERBOSE_MAKEFILE ON CACHE BOOL "")
Then run::
west config build.cmake-args "-C ~/my-cache.cmake"
See the `cmake(1) manual page`_ and the `set() command`_ documentation for
more details.
.. _cmake(1) manual page:
https://cmake.org/cmake/help/latest/manual/cmake.1.html
.. _set() command:
https://cmake.org/cmake/help/latest/command/set.html
.. _west-building-config:
Configuration Options
@ -222,6 +300,10 @@ You can :ref:`configure <west-config-cmd>` ``west build`` using these options.
* - ``build.board_warn``
- Boolean, default ``true``. If ``false``, disables warnings when
``west build`` can't figure out the target board.
* - ``build.cmake-args``
- String. If present, the value will be split according to shell rules and
passed to CMake whenever a new build system is generated. See
:ref:`west-building-cmake-config`.
* - ``build.dir-fmt``
- String, default ``build``. The build folder format string, used by
west whenever it needs to create or locate a build folder. The currently

View file

@ -4,6 +4,7 @@
import argparse
import os
import shlex
from west import log
from west.configuration import config
@ -385,6 +386,10 @@ class Build(Forceable):
if self.args.cmake_opts:
cmake_opts.extend(self.args.cmake_opts)
user_args = config_get('cmake-args', None)
if user_args:
cmake_opts.extend(shlex.split(user_args))
# Invoke CMake from the current working directory using the
# -S and -B options (officially introduced in CMake 3.13.0).
# This is important because users expect invocations like this