pw_build/cmake.rst - pigweed/pigweed - Git at Google

 .. _module-pw_build-cmake:

 CMake
 =====
 Pigweed's `CMake`_ support is provided primarily for projects that have an
 existing CMake build and wish to integrate Pigweed without switching to a new
 build system.

 .. tip::
    To run upstream Pigweed's CMake build use the ``pw build`` command:

    .. code-block:: console

       pw build -r default_cmake

    This will install any required packages, generate cmake build files and invkoke ninja.

    .. code-block:: text

       19:36:58 INF [1/1] Starting ==> Recipe: default_cmake Targets: pw_run_tests.modules pw_apps pw_run_tests.pw_bluetooth Logfile: /out/build_default_cmake.txt
       19:36:58 INF [1/1] Run ==> pw --no-banner package install emboss
       19:36:59 INF [1/1] Run ==> pw --no-banner package install nanopb
       19:37:00 INF [1/1] Run ==> pw --no-banner package install boringssl
       19:37:10 INF [1/1] Run ==> cmake --fresh --debug-output -DCMAKE_MESSAGE_LOG_LEVEL=WARNING -S . -B ./out/cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=./pw_toolchain/host_clang/toolchain.cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -Ddir_pw_third_party_nanopb=./environment/packages/nanopb -Dpw_third_party_nanopb_ADD_SUBDIRECTORY=ON -Ddir_pw_third_party_emboss=./environment/packages/emboss -Ddir_pw_third_party_boringssl=./environment/packages/boringssl -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
       19:37:10 INF [1/1] Run ==> ninja -C out/cmake pw_apps pw_run_tests.modules pw_run_tests.pw_bluetooth

    :ref:`module-pw_watch` works with ``pw build`` as well. You can run the
    following to automatically rebuild when files change.

    .. code-block:: console

       pw build -r default_cmake --watch

 CMake functions
 ---------------
 CMake convenience functions are defined in ``pw_build/pigweed.cmake``.

 * ``pw_add_library_generic`` -- The base helper used to instantiate CMake
   libraries. This is meant for use in downstream projects as upstream Pigweed
   modules are expected to use ``pw_add_library``.
 * ``pw_add_library`` -- Add an upstream Pigweed library.
 * ``pw_add_facade_generic`` -- The base helper used to instantiate facade
   libraries. This is meant for use in downstream projects as upstream Pigweed
   modules are expected to use ``pw_add_facade``.
 * ``pw_add_facade`` -- Declare an upstream Pigweed facade.
 * ``pw_set_backend`` -- Set the backend library to use for a facade.
 * ``pw_add_test_generic`` -- The base helper used to instantiate test targets.
   This is meant for use in downstrema projects as upstream Pigweed modules are
   expected to use ``pw_add_test``.
 * ``pw_add_test`` -- Declare an upstream Pigweed test target.
 * ``pw_add_test_group`` -- Declare a target to group and bundle test targets.
 * ``pw_target_link_targets`` -- Helper wrapper around ``target_link_libraries``
   which only supports CMake targets and detects when the target does not exist.
   Note that generator expressions are not supported.
 * ``pw_add_global_compile_options`` -- Applies compilation options to all
   targets in the build. This should only be used to add essential compilation
   options, such as those that affect the ABI. Use ``pw_add_library`` or
   ``target_compile_options`` to apply other compile options.
 * ``pw_add_error_target`` -- Declares target which reports a message and causes
   a build failure only when compiled. This is useful when ``FATAL_ERROR``
   messages cannot be used to catch problems during the CMake configuration
   phase.
 * ``pw_parse_arguments`` -- Helper to parse CMake function arguments.
 * ``pw_rebase_paths`` -- Helper to update a set of file paths to be rooted on a
   new directory.

 See ``pw_build/pigweed.cmake`` for the complete documentation of these
 functions.

 Special libraries that do not fit well with these functions are created with the
 standard CMake functions, such as ``add_library`` and ``target_link_libraries``.

 Facades and backends
 --------------------
 The CMake build uses CMake cache variables for configuring
 :ref:`facades<docs-module-structure-facades>` and backends. Cache variables are
 similar to GN's build args set with ``gn args``. Unlike GN, CMake does not
 support multi-toolchain builds, so these variables have a single global value
 per build directory.

 The ``pw_add_module_facade`` function declares a cache variable named
 ``<module_name>_BACKEND`` for each facade. Cache variables can be awkward to
 work with, since their values only change when they're assigned, but then
 persist accross CMake invocations. These variables should be set in one of the
 following ways:

 * Prior to setting a backend, your application should include
   ``$ENV{PW_ROOT}/backends.cmake``. This file will setup all the backend targets
   such that any misspelling of a facade or backend will yield a warning.

   .. note::
     Zephyr developers do not need to do this, backends can be set automatically
     by enabling the appropriate Kconfig options.

 * Call ``pw_set_backend`` to set backends appropriate for the target in the
   target's toolchain file. The toolchain file is provided to ``cmake`` with
   ``-DCMAKE_TOOLCHAIN_FILE=<toolchain file>``.
 * Call ``pw_set_backend`` in the top-level ``CMakeLists.txt`` before other
   CMake code executes.
 * Set the backend variable at the command line with the ``-D`` option.

   .. code-block:: sh

      cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
          -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
          -Dpw_log_BACKEND=pw_log_basic

 * Temporarily override a backend by setting it interactively with ``ccmake`` or
   ``cmake-gui``.

 If the backend is set to a build target that does not exist, there will be an
 error message like the following:

 .. code-block::

    CMake Error at pw_build/pigweed.cmake:257 (message):
      my_module.my_facade's INTERFACE dep "my_nonexistent_backend" is not
      a target.
    Call Stack (most recent call first):
      pw_build/pigweed.cmake:238:EVAL:1 (_pw_target_link_targets_deferred_check)
      CMakeLists.txt:DEFERRED


 Toolchain setup
 ---------------
 In CMake, the toolchain is configured by setting CMake variables, as described
 in the `CMake documentation <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_.
 These variables are typically set in a toolchain CMake file passed to ``cmake``
 with the ``-D`` option (``-DCMAKE_TOOLCHAIN_FILE=path/to/file.cmake``).
 For Pigweed embedded builds, set ``CMAKE_SYSTEM_NAME`` to the empty string
 (``""``).

 Toolchains may set the ``pw_build_WARNINGS`` variable to a list of ``INTERFACE``
 libraries with compilation options for Pigweed's upstream libraries. This
 defaults to a strict set of warnings. Projects may need to use less strict
 compilation warnings to compile backends exposed to Pigweed code (such as
 ``pw_log``) that cannot compile with Pigweed's flags. If desired, Projects can
 access these warnings by depending on ``pw_build.warnings``.

 Third party libraries
 ---------------------
 The CMake build includes third-party libraries similarly to the GN build. A
 ``dir_pw_third_party_<library>`` cache variable is defined for each third-party
 dependency. The variable must be set to the absolute path of the library in
 order to use it. If the variable is empty
 (``if("${dir_pw_third_party_<library>}" STREQUAL "")``), the dependency is not
 available.

 Third-party dependencies are not automatically added to the build. They can be
 manually added with ``add_subdirectory`` or by setting the
 ``pw_third_party_<library>_ADD_SUBDIRECTORY`` option to ``ON``.

 Third party variables are set like any other cache global variable in CMake. It
 is recommended to set these in one of the following ways:

 * Set with the CMake ``set`` function in the toolchain file or a
   ``CMakeLists.txt`` before other CMake code executes.

   .. code-block:: cmake

      set(dir_pw_third_party_nanopb ${CMAKE_CURRENT_SOURCE_DIR}/external/nanopb CACHE PATH "" FORCE)

 * Set the variable at the command line with the ``-D`` option.

   .. code-block:: sh

      cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
          -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
          -Ddir_pw_third_party_nanopb=/path/to/nanopb

 * Set the variable interactively with ``ccmake`` or ``cmake-gui``.

 .. _module-pw_build-existing-cmake-project:

 Use Pigweed from an existing CMake project
 ------------------------------------------
 To use Pigweed libraries form a CMake-based project, simply include the Pigweed
 repository from a ``CMakeLists.txt``.

 .. code-block:: cmake

    add_subdirectory(path/to/pigweed pigweed)

 All module libraries will be available as ``module_name`` or
 ``module_name.sublibrary``.

 If desired, modules can be included individually.

 .. code-block:: cmake

    add_subdirectory(path/to/pigweed/pw_some_module pw_some_module)
    add_subdirectory(path/to/pigweed/pw_another_module pw_another_module)

 .. seealso::
    Additional Pigweed CMake function references:
    - :bdg-ref-primary-line:`module-pw_fuzzer-guides-using_fuzztest-toolchain`
    - :bdg-ref-primary-line:`module-pw_protobuf_compiler-cmake`
    - :bdg-ref-primary-line:`module-pw_unit_test-cmake`
	.. _module-pw_build-cmake:

	CMake
	=====
	Pigweed's `CMake`_ support is provided primarily for projects that have an
	existing CMake build and wish to integrate Pigweed without switching to a new
	build system.

	.. tip::
	To run upstream Pigweed's CMake build use the ``pw build`` command:

	.. code-block:: console

	pw build -r default_cmake

	This will install any required packages, generate cmake build files and invkoke ninja.

	.. code-block:: text

	19:36:58 INF [1/1] Starting ==> Recipe: default_cmake Targets: pw_run_tests.modules pw_apps pw_run_tests.pw_bluetooth Logfile: /out/build_default_cmake.txt
	19:36:58 INF [1/1] Run ==> pw --no-banner package install emboss
	19:36:59 INF [1/1] Run ==> pw --no-banner package install nanopb
	19:37:00 INF [1/1] Run ==> pw --no-banner package install boringssl
	19:37:10 INF [1/1] Run ==> cmake --fresh --debug-output -DCMAKE_MESSAGE_LOG_LEVEL=WARNING -S . -B ./out/cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=./pw_toolchain/host_clang/toolchain.cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -Ddir_pw_third_party_nanopb=./environment/packages/nanopb -Dpw_third_party_nanopb_ADD_SUBDIRECTORY=ON -Ddir_pw_third_party_emboss=./environment/packages/emboss -Ddir_pw_third_party_boringssl=./environment/packages/boringssl -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
	19:37:10 INF [1/1] Run ==> ninja -C out/cmake pw_apps pw_run_tests.modules pw_run_tests.pw_bluetooth

	:ref:`module-pw_watch` works with ``pw build`` as well. You can run the
	following to automatically rebuild when files change.

	.. code-block:: console

	pw build -r default_cmake --watch

	CMake functions
	---------------
	CMake convenience functions are defined in ``pw_build/pigweed.cmake``.

	* ``pw_add_library_generic`` -- The base helper used to instantiate CMake
	libraries. This is meant for use in downstream projects as upstream Pigweed
	modules are expected to use ``pw_add_library``.
	* ``pw_add_library`` -- Add an upstream Pigweed library.
	* ``pw_add_facade_generic`` -- The base helper used to instantiate facade
	libraries. This is meant for use in downstream projects as upstream Pigweed
	modules are expected to use ``pw_add_facade``.
	* ``pw_add_facade`` -- Declare an upstream Pigweed facade.
	* ``pw_set_backend`` -- Set the backend library to use for a facade.
	* ``pw_add_test_generic`` -- The base helper used to instantiate test targets.
	This is meant for use in downstrema projects as upstream Pigweed modules are
	expected to use ``pw_add_test``.
	* ``pw_add_test`` -- Declare an upstream Pigweed test target.
	* ``pw_add_test_group`` -- Declare a target to group and bundle test targets.
	* ``pw_target_link_targets`` -- Helper wrapper around ``target_link_libraries``
	which only supports CMake targets and detects when the target does not exist.
	Note that generator expressions are not supported.
	* ``pw_add_global_compile_options`` -- Applies compilation options to all
	targets in the build. This should only be used to add essential compilation
	options, such as those that affect the ABI. Use ``pw_add_library`` or
	``target_compile_options`` to apply other compile options.
	* ``pw_add_error_target`` -- Declares target which reports a message and causes
	a build failure only when compiled. This is useful when ``FATAL_ERROR``
	messages cannot be used to catch problems during the CMake configuration
	phase.
	* ``pw_parse_arguments`` -- Helper to parse CMake function arguments.
	* ``pw_rebase_paths`` -- Helper to update a set of file paths to be rooted on a
	new directory.

	See ``pw_build/pigweed.cmake`` for the complete documentation of these
	functions.

	Special libraries that do not fit well with these functions are created with the
	standard CMake functions, such as ``add_library`` and ``target_link_libraries``.

	Facades and backends
	--------------------
	The CMake build uses CMake cache variables for configuring
	:ref:`facades<docs-module-structure-facades>` and backends. Cache variables are
	similar to GN's build args set with ``gn args``. Unlike GN, CMake does not
	support multi-toolchain builds, so these variables have a single global value
	per build directory.

	The ``pw_add_module_facade`` function declares a cache variable named
	``<module_name>_BACKEND`` for each facade. Cache variables can be awkward to
	work with, since their values only change when they're assigned, but then
	persist accross CMake invocations. These variables should be set in one of the
	following ways:

	* Prior to setting a backend, your application should include
	``$ENV{PW_ROOT}/backends.cmake``. This file will setup all the backend targets
	such that any misspelling of a facade or backend will yield a warning.

	.. note::
	Zephyr developers do not need to do this, backends can be set automatically
	by enabling the appropriate Kconfig options.

	* Call ``pw_set_backend`` to set backends appropriate for the target in the
	target's toolchain file. The toolchain file is provided to ``cmake`` with
	``-DCMAKE_TOOLCHAIN_FILE=<toolchain file>``.
	* Call ``pw_set_backend`` in the top-level ``CMakeLists.txt`` before other
	CMake code executes.
	* Set the backend variable at the command line with the ``-D`` option.

	.. code-block:: sh

	cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
	-DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
	-Dpw_log_BACKEND=pw_log_basic

	* Temporarily override a backend by setting it interactively with ``ccmake`` or
	``cmake-gui``.

	If the backend is set to a build target that does not exist, there will be an
	error message like the following:

	.. code-block::

	CMake Error at pw_build/pigweed.cmake:257 (message):
	my_module.my_facade's INTERFACE dep "my_nonexistent_backend" is not
	a target.
	Call Stack (most recent call first):
	pw_build/pigweed.cmake:238:EVAL:1 (_pw_target_link_targets_deferred_check)
	CMakeLists.txt:DEFERRED


	Toolchain setup
	---------------
	In CMake, the toolchain is configured by setting CMake variables, as described
	in the `CMake documentation <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_.
	These variables are typically set in a toolchain CMake file passed to ``cmake``
	with the ``-D`` option (``-DCMAKE_TOOLCHAIN_FILE=path/to/file.cmake``).
	For Pigweed embedded builds, set ``CMAKE_SYSTEM_NAME`` to the empty string
	(``""``).

	Toolchains may set the ``pw_build_WARNINGS`` variable to a list of ``INTERFACE``
	libraries with compilation options for Pigweed's upstream libraries. This
	defaults to a strict set of warnings. Projects may need to use less strict
	compilation warnings to compile backends exposed to Pigweed code (such as
	``pw_log``) that cannot compile with Pigweed's flags. If desired, Projects can
	access these warnings by depending on ``pw_build.warnings``.

	Third party libraries
	---------------------
	The CMake build includes third-party libraries similarly to the GN build. A
	``dir_pw_third_party_<library>`` cache variable is defined for each third-party
	dependency. The variable must be set to the absolute path of the library in
	order to use it. If the variable is empty
	(``if("${dir_pw_third_party_<library>}" STREQUAL "")``), the dependency is not
	available.

	Third-party dependencies are not automatically added to the build. They can be
	manually added with ``add_subdirectory`` or by setting the
	``pw_third_party_<library>_ADD_SUBDIRECTORY`` option to ``ON``.

	Third party variables are set like any other cache global variable in CMake. It
	is recommended to set these in one of the following ways:

	* Set with the CMake ``set`` function in the toolchain file or a
	``CMakeLists.txt`` before other CMake code executes.

	.. code-block:: cmake

	set(dir_pw_third_party_nanopb ${CMAKE_CURRENT_SOURCE_DIR}/external/nanopb CACHE PATH "" FORCE)

	* Set the variable at the command line with the ``-D`` option.

	.. code-block:: sh

	cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
	-DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
	-Ddir_pw_third_party_nanopb=/path/to/nanopb

	* Set the variable interactively with ``ccmake`` or ``cmake-gui``.

	.. _module-pw_build-existing-cmake-project:

	Use Pigweed from an existing CMake project
	------------------------------------------
	To use Pigweed libraries form a CMake-based project, simply include the Pigweed
	repository from a ``CMakeLists.txt``.

	.. code-block:: cmake

	add_subdirectory(path/to/pigweed pigweed)

	All module libraries will be available as ``module_name`` or
	``module_name.sublibrary``.

	If desired, modules can be included individually.

	.. code-block:: cmake

	add_subdirectory(path/to/pigweed/pw_some_module pw_some_module)
	add_subdirectory(path/to/pigweed/pw_another_module pw_another_module)

	.. seealso::
	Additional Pigweed CMake function references:
	- :bdg-ref-primary-line:`module-pw_fuzzer-guides-using_fuzztest-toolchain`
	- :bdg-ref-primary-line:`module-pw_protobuf_compiler-cmake`
	- :bdg-ref-primary-line:`module-pw_unit_test-cmake`