cmake: introduction of ZephyrBuildConfiguration package

The ZephyrBuildConfiguration package allow downstream users to control
the Zephyr build system using a cmake package.

A Zephyr Build Configuration package allows for setting of additional
DTS_ROOT, BOARD_ROOT, and similar variables without having to patch
Zephyr repo, but it also allows for inclusion of additional boilerplate
code for more advanced use cases.

The repository or folder containing the Zephyr Build Configuration
package must be on toplevel in the Zephyr workspace.

Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
This commit is contained in:
Torsten Rasmussen 2020-05-13 23:05:28 +02:00 committed by Carles Cufí
commit 9adcabe38d
3 changed files with 81 additions and 0 deletions

View file

@ -89,6 +89,8 @@ if((NOT DEFINED ZEPHYR_BASE) AND (DEFINED ENV_ZEPHYR_BASE))
set(ZEPHYR_BASE ${ENV_ZEPHYR_BASE} CACHE PATH "Zephyr base")
endif()
find_package(ZephyrBuildConfiguration NAMES ZephyrBuild PATHS ${ZEPHYR_BASE}/../* QUIET NO_DEFAULT_PATH NO_POLICY_SCOPE)
# Note any later project() resets PROJECT_SOURCE_DIR
file(TO_CMAKE_PATH "${ZEPHYR_BASE}" PROJECT_SOURCE_DIR)

View file

@ -106,6 +106,18 @@ To get this value back into your current terminal environment, **you must run**
The value will be lost if you close the window, etc.; run ``zephyr-env.cmd``
again to get it back.
Option 4: Using Zephyr Build Configuration CMake package
--------------------------------------------------------
Choose this option if you want to make those variable settings shared among all
users of your project.
Using a :ref:`cmake_build_config_package` allows you to commit the shared
settings into the repository, so that all users can share them.
It also removes the need for running ``source zephyr-env.sh`` or
``zephyr-env.cmd`` when opening a new terminal.
.. _zephyr-env:
Zephyr Environment Scripts

View file

@ -382,6 +382,72 @@ Such a CMakeLists.txt could look as:
project(my_first_app)
.. _cmake_build_config_package:
Zephyr Build Configuration CMake package
****************************************
The Zephyr Build Configuration CMake package provides a possibility for a Zephyr based project to
control Zephyr build settings in a generic way.
It is similar to the use of ``.zephyrrc`` but with the possibility to automatically allow all users
to share the build configuration through the project repository.
But it also allows more advanced use cases than a ``.zephyrrc``-file, such as loading of additional
CMake boilerplate code.
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:
``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:
.. code-block:: none
<projects>/zephyr-workspace
├── zephyr
├── ...
└── zephyr application (can be named anything)
└── share/zephyrbuild-package/cmake/ZephyrBuildConfig.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
``<zephyr application>/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.
.. code-block:: cmake
# ZephyrBuildConfig.cmake sample code
# To ensure final path is absolute and does not contain ../.. in variable.
get_filename_component(APPLICATION_PROJECT_DIR
${CMAKE_CURRENT_LIST_DIR}/../../..
ABSOLUTE
)
# Add this project to list of board roots
list(APPEND BOARD_ROOT ${APPLICATION_PROJECT_DIR})
# Default to GNU Arm Embedded toolchain if no toolchain is set
if(NOT ENV{ZEPHYR_TOOLCHAIN_VARIANT})
set(ZEPHYR_TOOLCHAIN_VARIANT gnuarmemb)
find_program(GNU_ARM_GCC arm-none-eabi-gcc)
if(NOT ${GNU_ARM_GCC} STREQUAL GNU_ARM_GCC-NOTFOUND)
# The toolchain root is located above the path to the compiler.
get_filename_component(GNUARMEMB_TOOLCHAIN_PATH ${GNU_ARM_GCC}/../.. ABSOLUTE)
endif()
endif()
Zephyr CMake package source code
********************************
@ -428,3 +494,4 @@ The following is an overview of those files
.. _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