doc: Zephyr build configuration CMake package freestanding

Update to the Zephyr build configuration CMake package documentation
with description on how a Zephyr build configuration CMake package can
be located outside a Zephyr workspace.

Signed-off-by: Torsten Rasmussen <[email protected]>

Author: tejlmand

doc/guides/modules.rst

@@ -771,6 +771,8 @@ Each project in the ``west list`` output is tested like this:
 - If neither of those checks succeed, the project is not considered a module,
   and is not added to :makevar:`ZEPHYR_MODULES`.
 
+.. _modules_without_west:
+
 Without West
 ------------
 

doc/guides/zephyr_cmake_package.rst

@@ -125,6 +125,8 @@ In this example ``my_first_app`` is a Zephyr workspace application.
           installed using ``west``
 
 
+.. _freestanding_application:
+
 Zephyr freestanding application
 ===============================
 
@@ -453,6 +455,48 @@ A sample ``ZephyrBuildConfig.cmake`` can be seen below.
        endif()
    endif()
 
+Zephyr Build Configuration CMake package (Freestanding application)
+*******************************************************************
+
+The Zephyr Build Configuration CMake package can be located outside a Zephyr
+workspace, for example located with a :ref:`freestanding_application`.
+
+Create the build configuration as described in the previous section, and then
+refer to the location of your Zephyr Build Configuration CMake package using
+the CMake variable ``ZephyrBuildConfiguration_ROOT``.
+
+#. At the CMake command line, like this:
+
+   .. code-block:: console
+
+      cmake -DZephyrBuildConfiguration_ROOT=<path-to-build-config> ...
+
+#. At the top of your application's top level :file:`CMakeLists.txt`, like this:
+
+   .. code-block:: cmake
+
+      set(ZephyrBuildConfiguration_ROOT <path-to-build-config>)
+      find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+   If you choose this option, make sure to set the variable **before**  calling
+   ``find_package(Zephyr ...)``, as shown above.
+
+#. In a separate CMake script which is pre-loaded to populate the CMake cache,
+   like this:
+
+   .. code-block:: cmake
+
+      # Put this in a file with a name like "zephyr-settings.cmake"
+      set(ZephyrBuildConfiguration_ROOT <path-to-build-config>
+          CACHE STRING "pre-cached build config"
+      )
+
+   You can tell the build system to use this file by adding ``-C
+   zephyr-settings.cmake`` to your CMake command line.
+   This principle is useful when not using ``west`` as both this setting and
+   Zephyr modules can be specified using the same file.
+   See Zephyr module :ref:`modules_without_west`.
+
 Zephyr CMake package source code
 ********************************