CMake API reference

pw_build: Integrations for Bazel, GN, and CMake

Pigweed provides numerous CMake helper functions. Testing-related functions are defined and documented in pw_unit_test/test.cmake. Everything else comes from pw_build/pigweed.cmake. This page lists all of the helper functions alphabetically. The usage information is automatically pulled from the comments in pw_unit_test/test.cmake and pw_build/pigweed.cmake.

pw_add_error_target

# pw_add_error_target: Creates a CMake target which fails to build and prints a
#                      message
#
# This function prints a message and causes a build failure only if you attempt
# to build the target. This is useful when FATAL_ERROR messages cannot be used
# to catch problems during the CMake configuration phase.
#
# Args:
#
#   NAME: name to use for the target
#   MESSAGE: The message to print, prefixed with "ERROR: ". The message may be
#            composed of multiple pieces by passing multiple strings.
#

pw_add_facade

# Declares a module as a facade.
#
# Facades are declared as two libraries to avoid circular dependencies.
# Libraries that use the facade depend on a library named for the module. The
# module that implements the facade depends on a library named
# MODULE_NAME.facade.
#
# pw_add_facade accepts the same arguments as pw_add_library.
# It also accepts the following argument:
#
#  BACKEND - The name of the facade's backend variable.

pw_add_facade_generic

# pw_add_facade_generic: Creates a CMake facade library target.
#
# This is the base helper used to instantiate a facade library.
# It should only be used when adding a dependency on a custom
# facade library from your own project. When adding a dependency
# on an upstream Pigweed facade you should use pw_add_facade instead.
#
# Facades are declared as two libraries to avoid circular dependencies.
# Libraries that use the facade depend on the <name> of this target. The
# libraries that implement this facade have to depend on an internal library
# named <name>.facade.
#
# Required Args:
#
#   <name> - The name for the public facade target (<name>) for all users and
#            the suffixed facade target for backend implementers (<name.facade).
#   <type> - The library type which must be INTERFACE, OBJECT, STATIC, or
#            SHARED.
#   BACKEND - The name of the facade's backend variable.
#
# Optional Args:
#
#   SOURCES - source files for this library
#   HEADERS - header files for this library
#   PUBLIC_DEPS - public pw_target_link_targets arguments
#   PRIVATE_DEPS - private pw_target_link_targets arguments
#   PUBLIC_INCLUDES - public target_include_directories argument
#   PRIVATE_INCLUDES - public target_include_directories argument
#   PUBLIC_DEFINES - public target_compile_definitions arguments
#   PRIVATE_DEFINES - private target_compile_definitions arguments
#   PUBLIC_COMPILE_OPTIONS - public target_compile_options arguments
#   PRIVATE_COMPILE_OPTIONS_DEPS_BEFORE - private target_compile_options BEFORE
#     arguments from the specified deps's INTERFACE_COMPILE_OPTIONS. Note that
#     these deps are not pulled in as target_link_libraries. This should not be
#     exposed by the non-generic API.
#   PRIVATE_COMPILE_OPTIONS - private target_compile_options arguments
#   PUBLIC_LINK_OPTIONS - public target_link_options arguments
#   PRIVATE_LINK_OPTIONS - private target_link_options arguments

pw_add_global_compile_options

# Adds compiler options to all targets built by CMake. Flags may be added any
# time after this function is defined. The effect is global; all targets added
# before or after a pw_add_global_compile_options call will be built with the
# flags, regardless of where the files are located.
#
# pw_add_global_compile_options takes one optional named argument:
#
#   LANGUAGES: Which languages (ASM, C, CXX) to apply the options to. Flags
#       apply to all languages by default.
#
# All other arguments are interpreted as compiler options.

pw_add_library

# Creates a pw module library.
#
# Required Args:
#
#   <name> - The name of the library target to be created.
#   <type> - The library type which must be INTERFACE, OBJECT, STATIC or SHARED.
#
# Optional Args:
#
#   SOURCES - source files for this library
#   HEADERS - header files for this library
#   PUBLIC_DEPS - public pw_target_link_targets arguments
#   PRIVATE_DEPS - private pw_target_link_targets arguments
#   PUBLIC_INCLUDES - public target_include_directories argument
#   PRIVATE_INCLUDES - public target_include_directories argument
#   PUBLIC_DEFINES - public target_compile_definitions arguments
#   PRIVATE_DEFINES - private target_compile_definitions arguments
#   PUBLIC_COMPILE_OPTIONS - public target_compile_options arguments
#   PRIVATE_COMPILE_OPTIONS - private target_compile_options arguments
#   PUBLIC_LINK_OPTIONS - public target_link_options arguments
#   PRIVATE_LINK_OPTIONS - private target_link_options arguments
#   SANDBOX - whether to sandbox this library (ON/OFF); overrides
#     pw_ENABLE_CC_SANDBOX
#

pw_add_library_generic

# pw_add_library_generic: Creates a CMake library target.
#
# This is the base helper used to instantiate CMake libraries.
# It should only be used when adding a dependency on a custom library
# from your own project. When adding a dependency on an upstream
# Pigweed module you should use pw_add_library instead.
#
# Required Args:
#
#   <name> - The name of the library target to be created.
#   <type> - The library type which must be INTERFACE, OBJECT, STATIC, or
#            SHARED.
#
# Optional Args:
#
#   SOURCES - source files for this library
#   HEADERS - header files for this library
#   GENERATED_HEADERS - headers that will be generated when the target is built
#   PUBLIC_DEPS - public pw_target_link_targets arguments
#   PRIVATE_DEPS - private pw_target_link_targets arguments
#   PUBLIC_INCLUDES - public target_include_directories argument
#   PRIVATE_INCLUDES - public target_include_directories argument
#   PUBLIC_DEFINES - public target_compile_definitions arguments
#   PRIVATE_DEFINES - private target_compile_definitions arguments
#   PUBLIC_COMPILE_OPTIONS - public target_compile_options arguments
#   PRIVATE_COMPILE_OPTIONS - private target_compile_options arguments
#   PRIVATE_COMPILE_OPTIONS_DEPS_BEFORE - private target_compile_options BEFORE
#     arguments from the specified deps's INTERFACE_COMPILE_OPTIONS. Note that
#     these deps are not pulled in as target_link_libraries. This should not be
#     exposed by the non-generic API.
#   PUBLIC_LINK_OPTIONS - public target_link_options arguments
#   PRIVATE_LINK_OPTIONS - private target_link_options arguments
#   SANDBOX - whether to sandbox this library (ON/OFF); overrides
#     pw_ENABLE_CC_SANDBOX

pw_add_test

# pw_add_test: Declares a single unit test suite with Pigweed naming rules and
#              compiler warning options.
#
#   {NAME} depends on ${NAME}.run if pw_unit_test_AUTOMATIC_RUNNER is set, else
#          it depends on ${NAME}.bin
#   {NAME}.lib contains the provided test sources as a library target, which can
#              then be linked into a test executable.
#   {NAME}.bin is a standalone executable which contains only the test sources
#              specified in the pw_unit_test_template.
#   {NAME}.run which runs the unit test executable after building it if
#              pw_unit_test_AUTOMATIC_RUNNER is set, else it fails to build.
#
# Required Arguments:
#
#   NAME: name to use for the produced test targets specified above
#
# Optional Arguments:
#
#   SOURCES - source files for this library
#   HEADERS - header files for this library
#   PRIVATE_DEPS - private pw_target_link_targets arguments
#   PRIVATE_INCLUDES - public target_include_directories argument
#   PRIVATE_DEFINES - private target_compile_definitions arguments
#   PRIVATE_COMPILE_OPTIONS - private target_compile_options arguments
#   PRIVATE_LINK_OPTIONS - private target_link_options arguments
#
#  TODO(ewout, hepler): Deprecate the following legacy arguments
#   GROUPS - groups to which to add this test.
#

pw_add_test_generic

# pw_add_test_generic: Declares a single unit test suite.
#
# If you want your test suite to follow upstream Pigweed naming
# conventions and toolchain settings you should use pw_add_test
# instead.
#
#   {NAME} depends on ${NAME}.run if pw_unit_test_AUTOMATIC_RUNNER is set, else
#          it depends on ${NAME}.bin
#   {NAME}.lib contains the provided test sources as a library target, which can
#              then be linked into a test executable.
#   {NAME}.bin is a standalone executable which contains only the test sources
#              specified in the pw_unit_test_template.
#   {NAME}.run which runs the unit test executable after building it if
#              pw_unit_test_AUTOMATIC_RUNNER is set, else it fails to build.
#
# Required Arguments:
#
#   NAME: name to use for the produced test targets specified above
#
# Optional Arguments:
#
#   SOURCES - source files for this library
#   HEADERS - header files for this library
#   PRIVATE_DEPS - private pw_target_link_targets arguments
#   PRIVATE_INCLUDES - public target_include_directories argument
#   PRIVATE_DEFINES - private target_compile_definitions arguments
#   PRIVATE_COMPILE_OPTIONS_DEPS_BEFORE - private target_compile_options BEFORE
#     arguments from the specified deps's INTERFACE_COMPILE_OPTIONS. Note that
#     these deps are not pulled in as target_link_libraries. This should not be
#     exposed by the non-generic API.
#   PRIVATE_COMPILE_OPTIONS - private target_compile_options arguments
#   PRIVATE_LINK_OPTIONS - private target_link_options arguments
#   TEST_MAIN - overrides the default test main dependency
#
#  TODO(ewout, hepler): Deprecate the following legacy arguments
#   GROUPS - groups to which to add this test.
#

pw_add_test_group

# pw_add_test_group: Defines a collection of tests or other test groups.
#
# Creates the following targets:
#
#   {NAME} depends on ${NAME}.run if pw_unit_test_AUTOMATIC_RUNNER is set, else
#          it depends on ${NAME}.bin
#   {NAME}.bundle depends on ${NAME}.bundle.run if pw_unit_test_AUTOMATIC_RUNNER
#                 is set, else it depends on ${NAME}.bundle.bin
#   {NAME}.lib depends on ${NAME}.bundle.lib.
#   {NAME}.bin depends on the provided TESTS's <test_dep>.bin targets.
#   {NAME}.run depends on the provided TESTS's <test_dep>.run targets if
#              pw_unit_test_AUTOMATIC_RUNNER is set, else it fails to build.
#   {NAME}.bundle.lib contains the provided tests bundled as a library target,
#                     which can then be linked into a test executable.
#   {NAME}.bundle.bin standalone executable which contains the bundled tests.
#   {NAME}.bundle.run runs the {NAME}.bundle.bin test bundle executable after
#                     building it if pw_unit_test_AUTOMATIC_RUNNER is set, else
#                     it fails to build.
#
# Required Arguments:
#
#   NAME - The name of the executable target to be created.
#   TESTS - pw_add_test targets and pw_add_test_group bundles to be included in
#           this test bundle
#

pw_parse_arguments

# Wrapper around cmake_parse_arguments that fails with an error if any arguments
# remained unparsed or a required argument was not provided.
#
# All parsed arguments are prefixed with "arg_". This helper can only be used
# by functions, not macros.
#
# Required Arguments:
#
#   NUM_POSITIONAL_ARGS - PARSE_ARGV <N> arguments for
#                              cmake_parse_arguments
#
# Optional Args:
#
#   OPTION_ARGS - <option> arguments for cmake_parse_arguments
#   ONE_VALUE_ARGS - <one_value_keywords> arguments for cmake_parse_arguments
#   MULTI_VALUE_ARGS - <multi_value_keywords> arguments for
#                           cmake_parse_arguments
#   REQUIRED_ARGS - required arguments which must be set, these may any
#                        argument type (<option>, <one_value_keywords>, and/or
#                        <multi_value_keywords>)
#

pw_rebase_paths

# Rebases a set of files to a new root path and optionally appends extensions
# to them. This is particularly useful for file generators.
#
# Required Arguments:
#
#   <var>        - Variable to store the rebased file list in.
#   <new_root>   - The new root to rebase file paths onto.
#   <root>       - The current root to rebase off of.
#   <files>      - The list of files to rebase.
#   <extensions> - List of extensions to replace the existing file extensions
#                  with.
#
# Examples:
#
# list(APPEND files "public/proj/foo.def" "public/proj/bar.def")
#
# pw_rebase_paths(out_files "/tmp" "${CMAKE_CURRENT_SOURCE_DIR}/public"
#   ${files} "")
# out_files => [ "/tmp/proj/foo.def", "/tmp/proj/bar.def" ]
#
# pw_rebase_paths(out_files "/tmp" "${CMAKE_CURRENT_SOURCE_DIR}/public"
#   ${files} ".h")
# out_files => [ "/tmp/proj/foo.h", "/tmp/proj/bar.h" ]
#
# list (APPEND exts ".h" ".cc")
# pw_rebase_paths(out_files "/tmp" "${CMAKE_CURRENT_SOURCE_DIR}/public"
#   ${files} ${exts})
# out_files => [ "/tmp/proj/foo.h", "/tmp/proj/bar.h",
#                "/tmp/proj/foo.cc", "/tmp/proj/bar.cc" ]

pw_set_backend

# Sets which backend to use for the given facade's backend variable.

pw_target_link_targets

# pw_target_link_targets: CMake target only form of target_link_libraries.
#
# Helper wrapper around target_link_libraries which only supports CMake targets
# and detects when the target does not exist.
#
# NOTE: Generator expressions are not supported.
#
# Due to the processing order of list files, the list of targets has to be
# checked at the end of the root CMake list file. Instead of requiring all
# list files to be modified, a DEFER CALL is used.
#
# Required Args:
#
#   <name> - The library target to add the TARGET link dependencies to.
#
# Optional Args:
#
#   INTERFACE - interface target_link_libraries arguments which are all TARGETs.
#   PUBLIC - public target_link_libraries arguments which are all TARGETs.
#   PRIVATE - private target_link_libraries arguments which are all TARGETs.