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>

doc/guides/west/build-flash-debug.rst

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

scripts/west_commands/build.py

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