Lines Matching +full:cmake +full:-
1 .. _module-pw_build-cmake:
3 CMake title
5 .. pigweed-module-subpage::
8 Pigweed's `CMake`_ support is provided primarily for projects that have an
9 existing CMake build and wish to integrate Pigweed without switching to a new
13 To run upstream Pigweed's CMake build use the ``pw build`` command:
15 .. code-block:: console
17 pw build -r default_cmake
19 This will install any required packages, generate cmake build files and invkoke ninja.
21 .. code-block:: text
24 19:36:58 INF [1/1] Run ==> pw --no-banner package install emboss
25 19:36:59 INF [1/1] Run ==> pw --no-banner package install nanopb
26 19:37:00 INF [1/1] Run ==> pw --no-banner package install boringssl
27 …cmake --fresh --debug-output -DCMAKE_MESSAGE_LOG_LEVEL=WARNING -S . -B ./out/cmake -G Ninja -DCMAK…
28 …19:37:10 INF [1/1] Run ==> ninja -C out/cmake pw_apps pw_run_tests.modules pw_run_tests.pw_bluetoo…
30 :ref:`module-pw_watch` works with ``pw build`` as well. You can run the
33 .. code-block:: console
35 pw build -r default_cmake --watch
37 CMake functions
38 ---------------
39 CMake convenience functions are defined in ``pw_build/pigweed.cmake``.
41 * ``pw_add_library_generic`` -- The base helper used to instantiate CMake
44 * ``pw_add_library`` -- Add an upstream Pigweed library.
45 * ``pw_add_facade_generic`` -- The base helper used to instantiate facade
48 * ``pw_add_facade`` -- Declare an upstream Pigweed facade.
49 * ``pw_set_backend`` -- Set the backend library to use for a facade.
50 * ``pw_add_test_generic`` -- The base helper used to instantiate test targets.
53 * ``pw_add_test`` -- Declare an upstream Pigweed test target.
54 * ``pw_add_test_group`` -- Declare a target to group and bundle test targets.
55 * ``pw_target_link_targets`` -- Helper wrapper around ``target_link_libraries``
56 which only supports CMake targets and detects when the target does not exist.
58 * ``pw_add_global_compile_options`` -- Applies compilation options to all
62 * ``pw_add_error_target`` -- Declares target which reports a message and causes
64 messages cannot be used to catch problems during the CMake configuration
66 * ``pw_parse_arguments`` -- Helper to parse CMake function arguments.
67 * ``pw_rebase_paths`` -- Helper to update a set of file paths to be rooted on a
70 See ``pw_build/pigweed.cmake`` for the complete documentation of these
74 standard CMake functions, such as ``add_library`` and ``target_link_libraries``.
77 --------------------
78 The CMake build uses CMake cache variables for configuring
79 :ref:`facades<docs-module-structure-facades>` and backends. Cache variables are
80 similar to GN's build args set with ``gn args``. Unlike GN, CMake does not
81 support multi-toolchain builds, so these variables have a single global value
87 persist accross CMake invocations. These variables should be set in one of the
91 ``$ENV{PW_ROOT}/backends.cmake``. This file will setup all the backend targets
99 target's toolchain file. The toolchain file is provided to ``cmake`` with
100 ``-DCMAKE_TOOLCHAIN_FILE=<toolchain file>``.
101 * Call ``pw_set_backend`` in the top-level ``CMakeLists.txt`` before other
102 CMake code executes.
103 * Set the backend variable at the command line with the ``-D`` option.
105 .. code-block:: sh
107 cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
108 -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
109 -Dpw_log_BACKEND=pw_log_basic
112 ``cmake-gui``.
117 .. code-block::
119 CMake Error at pw_build/pigweed.cmake:257 (message):
123 pw_build/pigweed.cmake:238:EVAL:1 (_pw_target_link_targets_deferred_check)
128 ---------------
129 In CMake, the toolchain is configured by setting CMake variables, as described
130 in the `CMake documentation <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_.
131 These variables are typically set in a toolchain CMake file passed to ``cmake``
132 with the ``-D`` option (``-DCMAKE_TOOLCHAIN_FILE=path/to/file.cmake``).
144 ---------------------
145 The CMake build includes third-party libraries similarly to the GN build. A
146 ``dir_pw_third_party_<library>`` cache variable is defined for each third-party
152 Third-party dependencies are not automatically added to the build. They can be
156 Third party variables are set like any other cache global variable in CMake. It
159 * Set with the CMake ``set`` function in the toolchain file or a
160 ``CMakeLists.txt`` before other CMake code executes.
162 .. code-block:: cmake
166 * Set the variable at the command line with the ``-D`` option.
168 .. code-block:: sh
170 cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
171 -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
172 -Ddir_pw_third_party_nanopb=/path/to/nanopb
174 * Set the variable interactively with ``ccmake`` or ``cmake-gui``.
176 .. _module-pw_build-existing-cmake-project:
178 Use Pigweed from an existing CMake project
179 ------------------------------------------
180 To use Pigweed libraries form a CMake-based project, simply include the Pigweed
183 .. code-block:: cmake
192 .. code-block:: cmake
198 Additional Pigweed CMake function references:
199 - :bdg-ref-primary-line:`module-pw_fuzzer-guides-using_fuzztest-toolchain`
200 - :bdg-ref-primary-line:`module-pw_protobuf_compiler-cmake`
201 - :bdg-ref-primary-line:`module-pw_unit_test-cmake`