Lines Matching +full:cache +full:- +full:dependency +full:- +full:path
1 .. _module-pw_build:
3 --------
5 --------
14 .. _Ninja: https://ninja-build.org/
30 Pigweed development, and is the most tested and feature-rich build system
34 declarations that are used by upstream Pigweed to set some architecture-agnostic
41 -------------------------
46 * Only rely on pre-compiled tools provided by CIPD (or some other versioned,
47 pre-compiled binary distribution mechanism). This eliminates build artifact
51 using ``rebase_path("//path/to/my_script.py")``. Most of the time, Ninja
53 ``rebase_path("//path/to/my_script.py", root_build_dir)``). This ensures build
64 ------------
65 .. code-block::
80 cross-compilation, warning/error policy, etc. directly to toolchain
87 individual platform-specific toolchains extend the list by appending to the
91 deprecated. Default dependency functionality continues to exist for
94 #. **Optionally add link-time binding**
100 dependencies that would typically create dependency cycles. In order for the
101 implementation to be linked in, it must be added to the dependency tree of
105 instead late-bound by adding it as a direct dependency of the final linked
125 :ref:`module-pw_assert-assert-api`.
167 .. _module-pw_build-link-deps:
169 Link-only deps
170 --------------
171 It may be necessary to specify additional link-time dependencies that may not be
183 ---------------
184 GN templates for :ref:`Python build automation <docs-python-build>` are
185 described in :ref:`module-pw_build-python`.
193 .. _module-pw_build-cc_blob_library:
196 ------------------
200 passed-in files as arrays of ``std::byte``.
215 * ``file_path``: The file path for the binary blob.
231 .. code-block::
255 .. code-block::
272 .. code-block::
290 .. _module-pw_build-facade:
293 ---------
294 In their simplest form, a :ref:`facade<docs-module-structure-facades>` is a GN
295 build arg used to change a dependency at compile time. Pigweed targets configure
304 * ``$target_name``: the public-facing ``pw_source_set``, with a ``public_dep``
309 .. code-block::
318 Low-level facades like ``pw_assert`` cannot express all of their dependencies
319 due to the potential for dependency cycles. Facades with this issue may require
321 in ``pw_build_LINK_DEPS`` (see :ref:`module-pw_build-link-deps`). The
326 .. _module-pw_build-python-action:
329 ----------------
354 used. If ``stamp`` is a file path, that file is used as a stamp file. Like any
358 * ``working_directory``: Optional file path. When provided the current working
362 command, e.g. ``'/usr/bin/fakeroot --'`` will run the Python script within a
367 .. _module-pw_build-python-action-expressions:
393 .. code-block::
399 .. code-block::
411 ``rebase_path(path, root_build_dir)`` function. This function
412 converts the provided GN path or list of paths to be relative to the build
424 .. code-block::
426 "--database=<TARGET_FILE_IF_EXISTS(//alpha/bravo)>"
431 .. code-block::
433 "--database=/home/User/project/out/obj/alpha/bravo/bravo.elf"
436 ``--database=`` argument is omitted from the script arguments.
447 .. code-block::
453 .. code-block::
461 .. code-block::
468 "--database",
470 "--binary=<TARGET_FILE(//firmware/images:main)>",
475 .. _module-pw_build-evaluate-path-expressions:
478 ----------------------------
483 artifacts in a build system-agnostic manner.
487 files in-place.
489 Refer to ``pw_python_action``'s :ref:`module-pw_build-python-action-expressions`
495 sub-target of a larger template, rather than a standalone build target.
508 .. code-block::
545 .. _module-pw_build-pw_exec:
548 -------
558 * ``program``: The program to run. Can be a full path or just a name (in which
559 case $PATH is searched).
568 * ``env``: Optional list of key-value pairs defining environment variables for
570 * ``env_file``: Optional path to a file containing a list of newline-separated
571 key-value pairs defining environment variables for the program.
572 * ``args_file``: Optional path to a file containing additional positional
587 .. code-block::
594 "-c",
603 --------------
613 the inputs are modified but GN cannot express this dependency.
628 .. code-block::
647 ------
665 #. Path to source file or directory. Directories must end with a ``/``.
679 .. code-block::
692 .. code-block::
717 .. code-block::
729 .. _module-pw_build-relative-source-file-names:
732 -----------------------------
736 config is applied. This is primarily intended for side-band generation of
741 with ``-ffile-prefix-map``-like transformations applied) that can be used to
742 :ref:`generate a token database <module-pw_tokenizer-database-creation>`.
747 * ``outputs``: A required array with a single element: the path to write the
754 .. code-block::
770 .. code-block::
805 .. code-block::
815 Since ``unused`` isn't a transitive dependency of ``main``, its source files
816 are not included. Similarly, even though ``bar`` is not a direct dependency of
818 a transitive dependency.
826 -----------------------------------------------
827 In Pigweed's complex, multi-toolchain GN build it is not possible to build every
837 (an empty group) if the condition passes. Targets can add a dependency on a
843 ------------------------
849 wrapper, ``pw-wrap-ninja``, that displays additional real-time information about
853 .. code-block:: sh
855 pw-wrap-ninja -C out
861 .. code-block::
867 [ 6.1s] clang-tidy ../pw_log_rpc/log_service.cc
868 [ 6.1s] clang-tidy ../pw_log_rpc/log_service_test.cc
869 [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain.cc
870 [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain_test.cc
878 ``pw-wrap-ninja`` includes other useful functionality as well. The
879 ``--write-trace`` option writes a build trace to the specified path, which can
881 built-in ``chrome://tracing`` tool.
892 .. code-block:: sh
894 …cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_c…
902 .. code-block:: sh
904 ninja -C out/cmake_host pw_run_tests.modules
906 :ref:`module-pw_watch` supports CMake, so you can also run
908 .. code-block:: sh
910 pw watch -C out/cmake_host pw_run_tests.modules
913 ---------------
916 * ``pw_add_library_generic`` -- The base helper used to instantiate CMake
919 * ``pw_add_library`` -- Add an upstream Pigweed library.
920 * ``pw_add_facade_generic`` -- The base helper used to instantiate facade
923 * ``pw_add_facade`` -- Declare an upstream Pigweed facade.
924 * ``pw_set_backend`` -- Set the backend library to use for a facade.
925 * ``pw_add_test_generic`` -- The base helper used to instantiate test targets.
928 * ``pw_add_test`` -- Declare an upstream Pigweed test target.
929 * ``pw_add_test_group`` -- Declare a target to group and bundle test targets.
930 * ``pw_target_link_targets`` -- Helper wrapper around ``target_link_libraries``
933 * ``pw_add_global_compile_options`` -- Applies compilation options to all
937 * ``pw_add_error_target`` -- Declares target which reports a message and causes
941 * ``pw_parse_arguments`` -- Helper to parse CMake function arguments.
950 --------------------
951 The CMake build uses CMake cache variables for configuring
952 :ref:`facades<docs-module-structure-facades>` and backends. Cache variables are
954 support multi-toolchain builds, so these variables have a single global value
957 The ``pw_add_module_facade`` function declares a cache variable named
958 ``<module_name>_BACKEND`` for each facade. Cache variables can be awkward to
973 ``-DCMAKE_TOOLCHAIN_FILE=<toolchain file>``.
974 * Call ``pw_set_backend`` in the top-level ``CMakeLists.txt`` before other
976 * Set the backend variable at the command line with the ``-D`` option.
978 .. code-block:: sh
980 cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
981 -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
982 -Dpw_log_BACKEND=pw_log_basic
985 ``cmake-gui``.
990 .. code-block::
1001 ---------------
1003 in the `CMake documentation <https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html>`_.
1005 with the ``-D`` option (``-DCMAKE_TOOLCHAIN_FILE=path/to/file.cmake``).
1017 ---------------------
1018 The CMake build includes third-party libraries similarly to the GN build. A
1019 ``dir_pw_third_party_<library>`` cache variable is defined for each third-party
1020 dependency. The variable must be set to the absolute path of the library in
1022 (``if("${dir_pw_third_party_<library>}" STREQUAL "")``), the dependency is not
1025 Third-party dependencies are not automatically added to the build. They can be
1029 Third party variables are set like any other cache global variable in CMake. It
1035 .. code-block:: cmake
1037 set(dir_pw_third_party_nanopb ${CMAKE_CURRENT_SOURCE_DIR}/external/nanopb CACHE PATH "" FORCE)
1039 * Set the variable at the command line with the ``-D`` option.
1041 .. code-block:: sh
1043 cmake -B out/cmake_host -S "$PW_ROOT" -G Ninja \
1044 -DCMAKE_TOOLCHAIN_FILE=$PW_ROOT/pw_toolchain/host_clang/toolchain.cmake \
1045 -Ddir_pw_third_party_nanopb=/path/to/nanopb
1047 * Set the variable interactively with ``ccmake`` or ``cmake-gui``.
1050 ------------------------------------------
1051 To use Pigweed libraries form a CMake-based project, simply include the Pigweed
1054 .. code-block:: cmake
1056 add_subdirectory(path/to/pigweed pigweed)
1063 .. code-block:: cmake
1065 add_subdirectory(path/to/pigweed/pw_some_module pw_some_module)
1066 add_subdirectory(path/to/pigweed/pw_another_module pw_another_module)
1070 Bazel is currently very experimental, and only builds for host and ARM Cortex-M
1074 file. The built-in Bazel rules ``cc_binary``, ``cc_library``, and ``cc_test``
1078 In addition to wrapping the built-in rules, Pigweed also provides a custom
1081 .. code-block:: python
1102 linkopts = ["-T $(location :some_linker_script)"],
1106 `open source <https://github.com/silvergasp/bazel-embedded>`_ toolchains. The
1110 though slightly more hermetic. The host toolchain is based around clang-11 which
1111 has a system dependency on 'libtinfo.so.5' which is often included as part of
1115 .. code-block:: sh
1122 The ARM Cortex-M Bazel toolchains are based around gcc-arm-non-eabi and are
1123 entirely hermetic. You can target Cortex-M, by using the platforms command line
1127 .. code-block:: sh
1129 bazel build //:your_target --platforms=@pigweed//pw_build/platforms:cortex_m0
1130 bazel build //:your_target --platforms=@pigweed//pw_build/platforms:cortex_m1
1131 bazel build //:your_target --platforms=@pigweed//pw_build/platforms:cortex_m3
1132 bazel build //:your_target --platforms=@pigweed//pw_build/platforms:cortex_m4
1133 bazel build //:your_target --platforms=@pigweed//pw_build/platforms:cortex_m7
1135 --platforms=@pigweed//pw_build/platforms:cortex_m4_fpu
1137 --platforms=@pigweed//pw_build/platforms:cortex_m7_fpu
1148 .. code-block:: python
1158 .. code-block:: python
1168 .. code-block:: python
1189 .. code-block:: python
1192 --platforms=@your_repo//build_settings:nucleo_l432kc
1198 .. code-block:: python