diff --git a/cmake/modules/zephyr_default.cmake b/cmake/modules/zephyr_default.cmake index 8d651e0b8fe..98a580c3a2d 100644 --- a/cmake/modules/zephyr_default.cmake +++ b/cmake/modules/zephyr_default.cmake @@ -24,6 +24,7 @@ message(STATUS "Application: ${APPLICATION_SOURCE_DIR}") # to CMake 3.20; this produces different binaries. message(STATUS "CMake version: ${CMAKE_VERSION}") +# Find and execute workspace build configuration find_package(ZephyrBuildConfiguration QUIET NO_POLICY_SCOPE NAMES ZephyrBuild @@ -36,6 +37,19 @@ find_package(ZephyrBuildConfiguration NO_CMAKE_SYSTEM_PACKAGE_REGISTRY ) +# Find and execute application-specific build configuration +find_package(ZephyrAppConfiguration + QUIET NO_POLICY_SCOPE + NAMES ZephyrApp + PATHS ${APPLICATION_SOURCE_DIR} + NO_CMAKE_PATH + NO_CMAKE_ENVIRONMENT_PATH + NO_SYSTEM_ENVIRONMENT_PATH + NO_CMAKE_PACKAGE_REGISTRY + NO_CMAKE_SYSTEM_PATH + NO_CMAKE_SYSTEM_PACKAGE_REGISTRY +) + # Test and error-out if we are affected by the PyPI CMake 3.22.1 / 3.22.2 bug if(${CMAKE_VERSION} VERSION_EQUAL 3.22.1 OR ${CMAKE_VERSION} VERSION_EQUAL 3.22.2) # It seems only pip-installed builds are affected so we test to see if we are affected diff --git a/doc/build/zephyr_cmake_package.rst b/doc/build/zephyr_cmake_package.rst index c10e126cee0..fd8eeadd270 100644 --- a/doc/build/zephyr_cmake_package.rst +++ b/doc/build/zephyr_cmake_package.rst @@ -313,46 +313,72 @@ Such a CMakeLists.txt could look as: .. _cmake_build_config_package: -Zephyr Build Configuration CMake package -**************************************** +Zephyr Build Configuration CMake packages +***************************************** -The Zephyr Build Configuration CMake package provides a possibility for a Zephyr based project to -control Zephyr build settings in a generic way. +There are two Zephyr Build configuration packages which provide control over the build +settings in Zephyr in a more generic way. These packages are: -It is similar to the per-user ``.zephyrrc`` file that can be used to set :ref:`env_vars`, but it -sets CMake variables instead. It also allows you to automatically share the build configuration -among all users through the project repository. It also allows more advanced use cases, such as loading -of additional CMake boilerplate code. +* **ZephyrBuildConfiguration**: Applies to all Zephyr applications in the workspace +* **ZephyrAppConfiguration**: Applies only to the application you are currently building -The Zephyr Build Configuration CMake package will be loaded in the Zephyr boilerplate code after -initial properties and ``ZEPHYR_BASE`` has been defined, but before CMake code execution. -This allows the Zephyr Build Configuration CMake package to setup or extend properties such as: +They are similar to the per-user :file:`.zephyrrc` file that can be used to set :ref:`env_vars`, +but they set CMake variables instead. They also allow you to automatically share the build +configuration among all users through the project repository. They also allow more advanced use +cases, such as loading of additional CMake boilerplate code. + +The Zephyr Build Configuration CMake packages will be loaded in the Zephyr boilerplate code after +initial properties and ``ZEPHYR_BASE`` has been defined, but before CMake code execution. The +ZephyrBuildConfiguration is included first and ZephyrAppConfiguration afterwards. That means the +application-specific package could override the workspace settings, if needed. +This allows the Zephyr Build Configuration CMake packages to setup or extend properties such as: ``DTS_ROOT``, ``BOARD_ROOT``, ``TOOLCHAIN_ROOT`` / other toolchain setup, fixed overlays, and any other property that can be controlled. It also allows inclusion of additional boilerplate code. -To provide a Zephyr Build Configuration CMake package, create ``ZephyrBuildConfig.cmake`` and place -it in a Zephyr workspace top-level folder as: +To provide a ZephyrBuildConfiguration or ZephyrAppConfiguration, create +:file:`ZephyrBuildConfig.cmake` and/or :file:`ZephyrAppConfig.cmake` respectively and place them +in the appropriate location. The CMake ``find_package`` mechanism will search for these files with +the steps below. Other default CMake package search paths and hints are disabled and there is no +version checking implemented for these packages. This also means that these packages cannot be +installed in the CMake package registry. The search steps are: + +1. If ``ZephyrBuildConfiguration_ROOT``, or ``ZephyrAppConfiguration_ROOT`` respectively, is set, + search within this prefix path. If a matching file is found, execute this file. If no matching + file is found, go to step 2. +2. Search within ``${ZEPHYR_BASE}/../*``, or ``${APPLICATION_SOURCE_DIR}`` respectively. If a + matching file is found, execute this file. If no matching file is found, abort the search. + +It is recommended to place the files in the default paths from step 2, but with the +``_ROOT`` variables you have the flexibility to place them anywhere. This is +especially necessary for freestanding applications, for which the default path to +ZephyrBuildConfiguration usually does not work. In this case the ``_ROOT`` variables +can be set on the CMake command line, **before** ``find_package(Zephyr ...)``, as environment +variable or from a CMake cache initialization file with the ``-C`` command line option. + +.. note:: The ``_ROOT`` variables, as well as the default paths, are just the prefixes + to the search path. These prefixes get combined with additional path suffixes, which together + form the actual search path. Any combination that honors the + `CMake package search procedure`_ is valid and will work. + +If you want to completely disable the search for these packages, you can use the special CMake +``CMAKE_DISABLE_FIND_PACKAGE_`` variable for that. Just set +``CMAKE_DISABLE_FIND_PACKAGE_ZephyrBuildConfiguration`` or +``CMAKE_DISABLE_FIND_PACKAGE_ZephyrAppConfiguration`` to ``TRUE`` to disable the package. + +An example folder structure could look like this: .. code-block:: none /zephyr-workspace ├── zephyr ├── ... - └── zephyr application (can be named anything) - └── share/zephyrbuild-package/cmake/ZephyrBuildConfig.cmake + ├── manifest repo (can be named anything) + │ └── cmake/ZephyrBuildConfig.cmake + ├── ... + └── zephyr application + └── share/zephyrapp-package/cmake/ZephyrAppConfig.cmake -The Zephyr Build Configuration CMake package will not search in any CMake default search paths, and -thus cannot be installed in the CMake package registry. There will be no version checking on the -Zephyr Build Configuration package. - -.. note:: ``share/zephyrbuild-package/cmake/ZephyrBuildConfig.cmake`` follows the same folder - structure as the Zephyr CMake package. - - It is possible to place ``ZephyrBuildConfig.cmake`` directly in a - ``/cmake`` folder or another folder, as long as that folder is - honoring the `CMake package search`_ algorithm. - -A sample ``ZephyrBuildConfig.cmake`` can be seen below. +A sample :file:`ZephyrBuildConfig.cmake` can be seen below. .. code-block:: cmake @@ -377,48 +403,6 @@ 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:`zephyr-freestanding-app`. - -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= ... - -#. At the top of your application's top level :file:`CMakeLists.txt`, like this: - - .. code-block:: cmake - - set(ZephyrBuildConfiguration_ROOT ) - 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 - 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 ******************************** @@ -461,4 +445,4 @@ The following is an overview of the files in these directories: .. _CMake package: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html .. _CMake user package registry: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#user-package-registry .. _CMake package version: https://cmake.org/cmake/help/latest/command/find_package.html#version-selection -.. _CMake package search: https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure +.. _CMake package search procedure: https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure