pw_build/BUILD.gn - pigweed/pigweed - Git at Google

 # Copyright 2020 The Pigweed Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you may not
 # use this file except in compliance with the License. You may obtain a copy of
 # the License at
 #
 #     https://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations under
 # the License.

 import("//build_overrides/pigweed.gni")

 import("$dir_pw_build/cc_blob_library.gni")
 import("$dir_pw_build/python.gni")
 import("$dir_pw_build/relative_source_file_names.gni")
 import("$dir_pw_docgen/docs.gni")
 import("$dir_pw_toolchain/generate_toolchain.gni")
 import("$dir_pw_toolchain/traits.gni")
 import("$dir_pw_unit_test/test.gni")
 import("target_types.gni")

 # IMPORTANT: The compilation flags in this file must be kept in sync with
 #            the CMake flags pw_build/CMakeLists.txt.

 # TODO: b/301262374 - Provide a better way to detect the compiler type.
 is_clang = defined(pw_toolchain_SCOPE.cc) &&
            get_path_info(pw_toolchain_SCOPE.cc, "file") == "clang"

 config("colorize_output") {
   if (pw_build_COLORIZE_OUTPUT) {
     cflags = [
       # Colorize output. Ninja's Clang invocation disables color by default.
       "-fdiagnostics-color",
     ]
     ldflags = cflags
   }
 }

 config("debugging") {
   # Enable debug symbol generation. This has no effect on final code size.
   cflags = [ "-g" ]
 }

 config("extra_debugging") {
   # Include things like macro expansion in debug info.
   cflags = [ "-g3" ]
 }

 # Optimization levels
 config("optimize_debugging") {
   cflags = [ "-Og" ]
   ldflags = cflags
 }

 config("optimize_speed") {
   cflags = [ "-O2" ]
   ldflags = cflags
 }

 config("optimize_more_speed") {
   cflags = [ "-O3" ]
   ldflags = cflags
 }

 config("optimize_size") {
   cflags = [ "-Os" ]
   ldflags = cflags
 }

 config("enable_clang_fixed_point_types") {
   if (is_clang) {
     cflags = [ "-ffixed-point" ]
   }
 }

 config("enable_clang_mlinliner") {
   cflags = [
     # Enable ML inliner.
     "-mllvm",
     "-enable-ml-inliner=release",
   ]
 }

 config("enable_clang_gvn_sink_hoist") {
   cflags = [
     # Enable GVN sink/hoist.
     "-mllvm",
     "-enable-gvn-sink=1",
     "-mllvm",
     "-enable-gvn-hoist=1",
   ]
 }

 config("optimize_size_clang") {
   cflags = [ "-Oz" ]
   ldflags = [
     # Identical Code Folding optimization
     "-Wl,--icf=all",

     # LLD does not recognize `Oz` which is a compiler front-end flag.
     "-Wl,-O2",
   ]
   ldflags += cflags
 }

 # Standard compiler flags to reduce output binary size.
 config("reduced_size") {
   cflags = [
     "-fno-common",
     "-fno-exceptions",
     "-ffunction-sections",
     "-fdata-sections",
     "-fomit-frame-pointer",
   ]
   cflags_cc = [ "-fno-rtti" ]

   if (current_os == "mac" || current_os == "ios") {
     # Delete unreferenced sections. Helpful with -ffunction-sections.
     ldflags = [ "-Wl,-dead_strip" ]
   } else {
     # Delete unreferenced sections. Helpful with -ffunction-sections.
     ldflags = [ "-Wl,--gc-sections" ]
   }
 }

 config("rust_edition_2015") {
   rustflags = [ "--edition=2015" ]
 }

 config("rust_edition_2018") {
   rustflags = [ "--edition=2018" ]
 }

 config("rust_edition_2021") {
   rustflags = [ "--edition=2021" ]
 }

 config("strict_warnings") {
   cflags = [
     "-Wall",
     "-Wextra",
     "-Wimplicit-fallthrough",
     "-Wcast-qual",
     "-Wundef",
     "-Wpointer-arith",

     # Make all warnings errors, except for the exemptions below.
     "-Werror",
     "-Wno-error=cpp",  # preprocessor #warning statement
     "-Wno-error=deprecated-declarations",  # [[deprecated]] attribute
   ]
   cflags_cc = [ "-Wnon-virtual-dtor" ]
 }

 # Thread safety warnings are only supported by Clang.
 config("clang_thread_safety_warnings") {
   cflags = [ "-Wthread-safety" ]
   defines = [ "_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS=1" ]
 }

 # This config contains warnings that we don't necessarily recommend projects
 # enable, but are enabled for upstream Pigweed for maximum project
 # compatibility.
 config("extra_strict_warnings") {
   cflags = [
     "-Wshadow",
     "-Wredundant-decls",
   ]
   cflags_c = [ "-Wstrict-prototypes" ]
 }

 # This config contains warnings that are enabled for upstream Pigweed.
 # This config MUST NOT be used downstream to allow for warnings to be
 # added in the future without breaking downstream.
 config("internal_strict_warnings") {
   cflags = [ "-Wswitch-enum" ]

   if (is_clang) {
     cflags += [ "-Wextra-semi" ]
   } else {
     # TODO: b/306734552 - On GCC, this only works as a C++ flag.
     cflags_cc = [ "-Wextra-semi" ]
   }

   # TODO: b/243069432 - Enable pedantic warnings on Windows when they pass.
   if (host_os != "win") {
     configs = [ ":pedantic_warnings" ]
   }
 }

 config("pedantic_warnings") {
   cflags = [
     # Enable -Wpedantic, but disable a few warnings.
     "-Wpedantic",

     # Allow designated initializers, which were added in C++20 but widely
     # supported prior and permitted by the Google style guide.
     "-Wno-c++20-designator",

     # Allow empty ... arguments in macros, which are permitted in C++20 but
     # widely supported prior.
     "-Wno-gnu-zero-variadic-macro-arguments",
   ]

   if (pw_toolchain_CXX_STANDARD < pw_toolchain_STANDARD.CXX17) {
     # Allow C++17 attributes in C++14, since Pigweed targets C++17 or newer.
     cflags += [ "-Wno-c++17-attribute-extensions" ]
   }

   # TODO: b/333712899 - Enable C23 extension warnings.
   cflags += [ "-Wno-c23-extensions" ]

   # TODO: b/335021928 - Enable C++ 20 extension warnings.
   cflags += [ "-Wno-c++20-extensions" ]

   # TODO: b/335328444 - Enable C++ 20 extension warnings.
   cflags += [ "-Wno-deprecated-pragma" ]
 }

 # Numeric conversion warnings.
 #
 # Originally Pigweed didn't enable this, but we ultimately decided to turn it
 # on since it caused issues with downstream project that enable this warning.
 #
 # b/259746255 tracks converting everything to build with this warning.
 config("conversion_warnings") {
   # TODO: b/260629756 - Remove Windows restriction once fixed for Windows + GCC.
   if (host_os != "win") {
     cflags = [ "-Wconversion" ]
   }
 }

 config("cpp14") {
   cflags_cc = [ "-std=c++14" ]
 }

 config("cpp17") {
   cflags_cc = [
     "-std=c++17",

     # Allow uses of the register keyword, which may appear in C headers.
     "-Wno-register",
   ]
 }

 config("cpp20") {
   cflags_cc = [
     "-std=c++20",
     "-Wno-register",
   ]
 }

 # Selects the C++ standard to used based on the pw_toolchain_CXX_STANDARD
 # toolchain trait.
 config("toolchain_cpp_standard") {
   if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX14) {
     configs = [ ":cpp14" ]
   } else if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX17) {
     configs = [ ":cpp17" ]
   } else if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX20) {
     configs = [ ":cpp20" ]
   } else {
     assert(false,
            "Unexpected pw_toolchain_CXX_STANDARD value: " +
                pw_toolchain_CXX_STANDARD)
   }
 }

 # Removes system-dependent prefixes from macros like __FILE__ and debug symbols.
 #
 # All compilation is relative to root_build_dir. The root_build_dir path is
 # arbitrary, so it must be removed to make builds reproducible. This config
 # remaps paths as if compilation occurred from the repository root instead of
 # root_build_dir. Paths that include root_build_dir are updated to standardize
 # on out/ as the build directory.
 #
 # If an ELF is built from a directory other than "out/", debuggers will be able
 # to locate in-tree sources, but may have issues finding generated sources in
 # the output directory. This can be worked around in a few ways:
 #
 #   - Use GDB's `set substitute-path <from> <to>` option to remap paths.
 #   - Rebuild from out/.
 #   - Symlink out/ to the build directory.
 #   - Temporarily disable these transformations.
 #
 # If an ELF is built from "out/", debuggers will be able to locate all sources,
 # including generated sources, when run from the repo root.
 config("relative_paths") {
   # Apply a series of file-prefix-map transformations. Only the first matching
   # option applies.
   #
   # GCC applies these in reverse order due to building iterating through a
   # recursively constructed linked list:
   # inclusive-language: disable
   # https://github.com/gcc-mirror/gcc/blob/master/gcc/file-prefix-map.cc#L41.
   # inclusive-language: enable
   #
   # Clang currently does not have a set forwards or backwards application order
   # due to storing them in a std::map (that reorders lexicogrpahically by key):
   # https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/CodeGenOptions.h#L209.
   #
   # TODO: b/278906020 - Tracks merging in an upstream change to LLVM to that will
   # enforce clang applying these transformations in order. Until then, there
   # will be issues with the debug and coverage information while using build
   # directories that are more than a single directory from the root project
   # directory. This is due to "=out/" always being applied first due to the
   # left-hand side of the = being "", which is always ordered first in the
   # std::map.
   _transformations = [
     # Remap absolute prefixes for files in the output directory to out/.
     rebase_path(root_build_dir) + "/=out/",

     # Remove the path to the out directory so the ELF is relative to the root.
     rebase_path(root_build_dir) + "=",

     # Remove any absolute paths to the repo root.
     rebase_path("//") + "=",

     # Remove the relative path from the build directory to the root, which is
     # the prefix of in-tree sources.
     rebase_path("//", root_build_dir) + "=",

     # Prepend out/ to any unmatched files, which are in the output directory.
     "=out/",

     # Repeat the replacements in reverse order since GCC applies them backwards.
     rebase_path("//", root_build_dir) + "=",
     rebase_path("//") + "=",
     rebase_path(root_build_dir) + "=",
     rebase_path(root_build_dir) + "/=out/",
   ]

   cflags = []

   foreach(transform, _transformations) {
     cflags += [ "-ffile-prefix-map=" + transform ]
   }

   # Write the transformations to a well known path so that other utilities
   # that need to present file names that match the compiler's __FILE__
   # macro can apply the same transformation.
   write_file(pw_build_RELATIVE_PATH_TRANSFORM_JSON, _transformations, "json")
 }

 # This group is linked into all pw_executable, pw_static_library, and
 # pw_shared_library targets. This makes it possible to ensure symbols are
 # defined without a dependency on them.
 #
 # pw_build_LINK_DEPS should only be used when necessary. For example,
 # pw_assert relies on pw_build_LINK_DEPS to avoid circular dependencies
 # in GN. In almost all other cases, build targets should explicitly depend on
 # the other targets they use.
 #
 # pw_build_TOOLCHAIN_LINK_DEPS is used to define dependencies introduced by
 # the various toolchains created under pw_toolchain module in GN. For example,
 # LLVM compiler-rt builtin libraries, or the arm-none-eabi newlib interface
 # stubs.
 group("link_deps") {
   deps = pw_build_LINK_DEPS + pw_build_TOOLCHAIN_LINK_DEPS
 }

 # This empty target is used as the default value for module configurations.
 # Projects may set pw_build_DEFAULT_MODULE_CONFIG to a different GN target that
 # overrides modules' configuration options via macro definitions or a header
 # forcibly included with `-include`.
 group("empty") {
 }

 config("default_config") {
   include_dirs = [ "public" ]
 }

 # Linker script utility PW_MUST_PLACE
 pw_source_set("must_place") {
   public_configs = [ ":default_config" ]
   public = [ "public/pw_build/must_place.ld.h" ]
 }

 pw_doc_group("docs") {
   sources = [
     "bazel.rst",
     "cmake.rst",
     "docs.rst",
     "gn.rst",
     "linker_scripts.rst",
     "project_builder.rst",
     "python.rst",
   ]
 }

 config("module_config_test_config") {
   visibility = [ ":*" ]
   defines = [ "PW_THREAD_FREERTOS_CONFIG_JOINING_ENABLED=1" ]
 }

 # Pigweed upstream does not use the default toolchain, but other projects may
 # use it. To support using pw_build from the default toolchain without fully
 # configuring the Pigweed build, only instantiate the pw_build tests for a
 # non-default toolchain.
 if (current_toolchain != default_toolchain) {
   pw_test("cc_blob_library_test") {
     sources = [ "cc_blob_library_test.cc" ]
     deps = [ ":test_blob" ]
   }

   pw_test("module_config_test") {
     public_configs = [ ":module_config_test_config" ]
     sources = [ "module_config_test.cc" ]
     deps = [ "$dir_pw_thread_freertos:config" ]
   }

   pw_cc_blob_library("test_blob") {
     out_header = "pw_build/test_blob.h"
     namespace = "test::ns"
     blobs = [
       {
         file_path = "test_blob_0123.bin"
         symbol_name = "kFirstBlob0123"
         alignas = 512
       },
       {
         file_path = "test_blob_0123.bin"
         symbol_name = "kSecondBlob0123"
       },
     ]
     visibility = [ ":*" ]
   }

   # file_prefix_map_test verifies that the -ffile-prefix-map option is applied
   # correctly.

   # File paths should be relative to the root of the GN build.
   _test_header = rebase_path("pw_build_private/file_prefix_map_test.h", "//")
   _path_test_define = [ "PW_BUILD_EXPECTED_HEADER_PATH=\"$_test_header\"" ]

   pw_test("file_prefix_map_test") {
     _source_path = rebase_path("file_prefix_map_test.cc", "//")

     sources = [ "file_prefix_map_test.cc" ]

     defines = _path_test_define +
               [ "PW_BUILD_EXPECTED_SOURCE_PATH=\"$_source_path\"" ]

     deps = [ ":file_prefix_map_generated_file" ]
   }

   # Generated file paths should be relative to the build directory.
   copy("generate_file_prefix_map_test_source") {
     sources = [ "file_prefix_map_test.cc" ]
     outputs = [ get_label_info(":file_prefix_map_test", "target_gen_dir") +
                 "/file_prefix_map_test_generated.cc" ]
     visibility = [ ":*" ]
   }

   pw_source_set("file_prefix_map_generated_file") {
     public = [ "pw_build_private/file_prefix_map_test.h" ]
     sources = get_target_outputs(":generate_file_prefix_map_test_source")
     deps = [ ":generate_file_prefix_map_test_source" ]

     _source_path = rebase_path(sources[0], root_build_dir)

     # The source file is prefixed with out/ since it's generated.
     defines = _path_test_define +
               [ "PW_BUILD_EXPECTED_SOURCE_PATH=\"out/$_source_path\"" ]
     include_dirs = [ "." ]  # Allow accessing file_prefix_map_test.h
     visibility = [ ":*" ]
   }

   pw_source_set("empty_main") {
     sources = [ "empty_main.cc" ]
     visibility = [ ":*" ]
   }

   pw_test_group("tests") {
     tests = [
       ":cc_blob_library_test",
       ":file_prefix_map_test",
     ]
   }
 }
	# Copyright 2020 The Pigweed Authors
	#
	# Licensed under the Apache License, Version 2.0 (the "License"); you may not
	# use this file except in compliance with the License. You may obtain a copy of
	# the License at
	#
	# https://www.apache.org/licenses/LICENSE-2.0
	#
	# Unless required by applicable law or agreed to in writing, software
	# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	# License for the specific language governing permissions and limitations under
	# the License.

	import("//build_overrides/pigweed.gni")

	import("$dir_pw_build/cc_blob_library.gni")
	import("$dir_pw_build/python.gni")
	import("$dir_pw_build/relative_source_file_names.gni")
	import("$dir_pw_docgen/docs.gni")
	import("$dir_pw_toolchain/generate_toolchain.gni")
	import("$dir_pw_toolchain/traits.gni")
	import("$dir_pw_unit_test/test.gni")
	import("target_types.gni")

	# IMPORTANT: The compilation flags in this file must be kept in sync with
	# the CMake flags pw_build/CMakeLists.txt.

	# TODO: b/301262374 - Provide a better way to detect the compiler type.
	is_clang = defined(pw_toolchain_SCOPE.cc) &&
	get_path_info(pw_toolchain_SCOPE.cc, "file") == "clang"

	config("colorize_output") {
	if (pw_build_COLORIZE_OUTPUT) {
	cflags = [
	# Colorize output. Ninja's Clang invocation disables color by default.
	"-fdiagnostics-color",
	]
	ldflags = cflags
	}
	}

	config("debugging") {
	# Enable debug symbol generation. This has no effect on final code size.
	cflags = [ "-g" ]
	}

	config("extra_debugging") {
	# Include things like macro expansion in debug info.
	cflags = [ "-g3" ]
	}

	# Optimization levels
	config("optimize_debugging") {
	cflags = [ "-Og" ]
	ldflags = cflags
	}

	config("optimize_speed") {
	cflags = [ "-O2" ]
	ldflags = cflags
	}

	config("optimize_more_speed") {
	cflags = [ "-O3" ]
	ldflags = cflags
	}

	config("optimize_size") {
	cflags = [ "-Os" ]
	ldflags = cflags
	}

	config("enable_clang_fixed_point_types") {
	if (is_clang) {
	cflags = [ "-ffixed-point" ]
	}
	}

	config("enable_clang_mlinliner") {
	cflags = [
	# Enable ML inliner.
	"-mllvm",
	"-enable-ml-inliner=release",
	]
	}

	config("enable_clang_gvn_sink_hoist") {
	cflags = [
	# Enable GVN sink/hoist.
	"-mllvm",
	"-enable-gvn-sink=1",
	"-mllvm",
	"-enable-gvn-hoist=1",
	]
	}

	config("optimize_size_clang") {
	cflags = [ "-Oz" ]
	ldflags = [
	# Identical Code Folding optimization
	"-Wl,--icf=all",

	# LLD does not recognize `Oz` which is a compiler front-end flag.
	"-Wl,-O2",
	]
	ldflags += cflags
	}

	# Standard compiler flags to reduce output binary size.
	config("reduced_size") {
	cflags = [
	"-fno-common",
	"-fno-exceptions",
	"-ffunction-sections",
	"-fdata-sections",
	"-fomit-frame-pointer",
	]
	cflags_cc = [ "-fno-rtti" ]

	if (current_os == "mac" \|\| current_os == "ios") {
	# Delete unreferenced sections. Helpful with -ffunction-sections.
	ldflags = [ "-Wl,-dead_strip" ]
	} else {
	# Delete unreferenced sections. Helpful with -ffunction-sections.
	ldflags = [ "-Wl,--gc-sections" ]
	}
	}

	config("rust_edition_2015") {
	rustflags = [ "--edition=2015" ]
	}

	config("rust_edition_2018") {
	rustflags = [ "--edition=2018" ]
	}

	config("rust_edition_2021") {
	rustflags = [ "--edition=2021" ]
	}

	config("strict_warnings") {
	cflags = [
	"-Wall",
	"-Wextra",
	"-Wimplicit-fallthrough",
	"-Wcast-qual",
	"-Wundef",
	"-Wpointer-arith",

	# Make all warnings errors, except for the exemptions below.
	"-Werror",
	"-Wno-error=cpp", # preprocessor #warning statement
	"-Wno-error=deprecated-declarations", # [[deprecated]] attribute
	]
	cflags_cc = [ "-Wnon-virtual-dtor" ]
	}

	# Thread safety warnings are only supported by Clang.
	config("clang_thread_safety_warnings") {
	cflags = [ "-Wthread-safety" ]
	defines = [ "_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS=1" ]
	}

	# This config contains warnings that we don't necessarily recommend projects
	# enable, but are enabled for upstream Pigweed for maximum project
	# compatibility.
	config("extra_strict_warnings") {
	cflags = [
	"-Wshadow",
	"-Wredundant-decls",
	]
	cflags_c = [ "-Wstrict-prototypes" ]
	}

	# This config contains warnings that are enabled for upstream Pigweed.
	# This config MUST NOT be used downstream to allow for warnings to be
	# added in the future without breaking downstream.
	config("internal_strict_warnings") {
	cflags = [ "-Wswitch-enum" ]

	if (is_clang) {
	cflags += [ "-Wextra-semi" ]
	} else {
	# TODO: b/306734552 - On GCC, this only works as a C++ flag.
	cflags_cc = [ "-Wextra-semi" ]
	}

	# TODO: b/243069432 - Enable pedantic warnings on Windows when they pass.
	if (host_os != "win") {
	configs = [ ":pedantic_warnings" ]
	}
	}

	config("pedantic_warnings") {
	cflags = [
	# Enable -Wpedantic, but disable a few warnings.
	"-Wpedantic",

	# Allow designated initializers, which were added in C++20 but widely
	# supported prior and permitted by the Google style guide.
	"-Wno-c++20-designator",

	# Allow empty ... arguments in macros, which are permitted in C++20 but
	# widely supported prior.
	"-Wno-gnu-zero-variadic-macro-arguments",
	]

	if (pw_toolchain_CXX_STANDARD < pw_toolchain_STANDARD.CXX17) {
	# Allow C++17 attributes in C++14, since Pigweed targets C++17 or newer.
	cflags += [ "-Wno-c++17-attribute-extensions" ]
	}

	# TODO: b/333712899 - Enable C23 extension warnings.
	cflags += [ "-Wno-c23-extensions" ]

	# TODO: b/335021928 - Enable C++ 20 extension warnings.
	cflags += [ "-Wno-c++20-extensions" ]

	# TODO: b/335328444 - Enable C++ 20 extension warnings.
	cflags += [ "-Wno-deprecated-pragma" ]
	}

	# Numeric conversion warnings.
	#
	# Originally Pigweed didn't enable this, but we ultimately decided to turn it
	# on since it caused issues with downstream project that enable this warning.
	#
	# b/259746255 tracks converting everything to build with this warning.
	config("conversion_warnings") {
	# TODO: b/260629756 - Remove Windows restriction once fixed for Windows + GCC.
	if (host_os != "win") {
	cflags = [ "-Wconversion" ]
	}
	}

	config("cpp14") {
	cflags_cc = [ "-std=c++14" ]
	}

	config("cpp17") {
	cflags_cc = [
	"-std=c++17",

	# Allow uses of the register keyword, which may appear in C headers.
	"-Wno-register",
	]
	}

	config("cpp20") {
	cflags_cc = [
	"-std=c++20",
	"-Wno-register",
	]
	}

	# Selects the C++ standard to used based on the pw_toolchain_CXX_STANDARD
	# toolchain trait.
	config("toolchain_cpp_standard") {
	if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX14) {
	configs = [ ":cpp14" ]
	} else if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX17) {
	configs = [ ":cpp17" ]
	} else if (pw_toolchain_CXX_STANDARD == pw_toolchain_STANDARD.CXX20) {
	configs = [ ":cpp20" ]
	} else {
	assert(false,
	"Unexpected pw_toolchain_CXX_STANDARD value: " +
	pw_toolchain_CXX_STANDARD)
	}
	}

	# Removes system-dependent prefixes from macros like __FILE__ and debug symbols.
	#
	# All compilation is relative to root_build_dir. The root_build_dir path is
	# arbitrary, so it must be removed to make builds reproducible. This config
	# remaps paths as if compilation occurred from the repository root instead of
	# root_build_dir. Paths that include root_build_dir are updated to standardize
	# on out/ as the build directory.
	#
	# If an ELF is built from a directory other than "out/", debuggers will be able
	# to locate in-tree sources, but may have issues finding generated sources in
	# the output directory. This can be worked around in a few ways:
	#
	# - Use GDB's `set substitute-path <from> <to>` option to remap paths.
	# - Rebuild from out/.
	# - Symlink out/ to the build directory.
	# - Temporarily disable these transformations.
	#
	# If an ELF is built from "out/", debuggers will be able to locate all sources,
	# including generated sources, when run from the repo root.
	config("relative_paths") {
	# Apply a series of file-prefix-map transformations. Only the first matching
	# option applies.
	#
	# GCC applies these in reverse order due to building iterating through a
	# recursively constructed linked list:
	# inclusive-language: disable
	# https://github.com/gcc-mirror/gcc/blob/master/gcc/file-prefix-map.cc#L41.
	# inclusive-language: enable
	#
	# Clang currently does not have a set forwards or backwards application order
	# due to storing them in a std::map (that reorders lexicogrpahically by key):
	# https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/CodeGenOptions.h#L209.
	#
	# TODO: b/278906020 - Tracks merging in an upstream change to LLVM to that will
	# enforce clang applying these transformations in order. Until then, there
	# will be issues with the debug and coverage information while using build
	# directories that are more than a single directory from the root project
	# directory. This is due to "=out/" always being applied first due to the
	# left-hand side of the = being "", which is always ordered first in the
	# std::map.
	_transformations = [
	# Remap absolute prefixes for files in the output directory to out/.
	rebase_path(root_build_dir) + "/=out/",

	# Remove the path to the out directory so the ELF is relative to the root.
	rebase_path(root_build_dir) + "=",

	# Remove any absolute paths to the repo root.
	rebase_path("//") + "=",

	# Remove the relative path from the build directory to the root, which is
	# the prefix of in-tree sources.
	rebase_path("//", root_build_dir) + "=",

	# Prepend out/ to any unmatched files, which are in the output directory.
	"=out/",

	# Repeat the replacements in reverse order since GCC applies them backwards.
	rebase_path("//", root_build_dir) + "=",
	rebase_path("//") + "=",
	rebase_path(root_build_dir) + "=",
	rebase_path(root_build_dir) + "/=out/",
	]

	cflags = []

	foreach(transform, _transformations) {
	cflags += [ "-ffile-prefix-map=" + transform ]
	}

	# Write the transformations to a well known path so that other utilities
	# that need to present file names that match the compiler's __FILE__
	# macro can apply the same transformation.
	write_file(pw_build_RELATIVE_PATH_TRANSFORM_JSON, _transformations, "json")
	}

	# This group is linked into all pw_executable, pw_static_library, and
	# pw_shared_library targets. This makes it possible to ensure symbols are
	# defined without a dependency on them.
	#
	# pw_build_LINK_DEPS should only be used when necessary. For example,
	# pw_assert relies on pw_build_LINK_DEPS to avoid circular dependencies
	# in GN. In almost all other cases, build targets should explicitly depend on
	# the other targets they use.
	#
	# pw_build_TOOLCHAIN_LINK_DEPS is used to define dependencies introduced by
	# the various toolchains created under pw_toolchain module in GN. For example,
	# LLVM compiler-rt builtin libraries, or the arm-none-eabi newlib interface
	# stubs.
	group("link_deps") {
	deps = pw_build_LINK_DEPS + pw_build_TOOLCHAIN_LINK_DEPS
	}

	# This empty target is used as the default value for module configurations.
	# Projects may set pw_build_DEFAULT_MODULE_CONFIG to a different GN target that
	# overrides modules' configuration options via macro definitions or a header
	# forcibly included with `-include`.
	group("empty") {
	}

	config("default_config") {
	include_dirs = [ "public" ]
	}

	# Linker script utility PW_MUST_PLACE
	pw_source_set("must_place") {
	public_configs = [ ":default_config" ]
	public = [ "public/pw_build/must_place.ld.h" ]
	}

	pw_doc_group("docs") {
	sources = [
	"bazel.rst",
	"cmake.rst",
	"docs.rst",
	"gn.rst",
	"linker_scripts.rst",
	"project_builder.rst",
	"python.rst",
	]
	}

	config("module_config_test_config") {
	visibility = [ ":*" ]
	defines = [ "PW_THREAD_FREERTOS_CONFIG_JOINING_ENABLED=1" ]
	}

	# Pigweed upstream does not use the default toolchain, but other projects may
	# use it. To support using pw_build from the default toolchain without fully
	# configuring the Pigweed build, only instantiate the pw_build tests for a
	# non-default toolchain.
	if (current_toolchain != default_toolchain) {
	pw_test("cc_blob_library_test") {
	sources = [ "cc_blob_library_test.cc" ]
	deps = [ ":test_blob" ]
	}

	pw_test("module_config_test") {
	public_configs = [ ":module_config_test_config" ]
	sources = [ "module_config_test.cc" ]
	deps = [ "$dir_pw_thread_freertos:config" ]
	}

	pw_cc_blob_library("test_blob") {
	out_header = "pw_build/test_blob.h"
	namespace = "test::ns"
	blobs = [
	{
	file_path = "test_blob_0123.bin"
	symbol_name = "kFirstBlob0123"
	alignas = 512
	},
	{
	file_path = "test_blob_0123.bin"
	symbol_name = "kSecondBlob0123"
	},
	]
	visibility = [ ":*" ]
	}

	# file_prefix_map_test verifies that the -ffile-prefix-map option is applied
	# correctly.

	# File paths should be relative to the root of the GN build.
	_test_header = rebase_path("pw_build_private/file_prefix_map_test.h", "//")
	_path_test_define = [ "PW_BUILD_EXPECTED_HEADER_PATH=\"$_test_header\"" ]

	pw_test("file_prefix_map_test") {
	_source_path = rebase_path("file_prefix_map_test.cc", "//")

	sources = [ "file_prefix_map_test.cc" ]

	defines = _path_test_define +
	[ "PW_BUILD_EXPECTED_SOURCE_PATH=\"$_source_path\"" ]

	deps = [ ":file_prefix_map_generated_file" ]
	}

	# Generated file paths should be relative to the build directory.
	copy("generate_file_prefix_map_test_source") {
	sources = [ "file_prefix_map_test.cc" ]
	outputs = [ get_label_info(":file_prefix_map_test", "target_gen_dir") +
	"/file_prefix_map_test_generated.cc" ]
	visibility = [ ":*" ]
	}

	pw_source_set("file_prefix_map_generated_file") {
	public = [ "pw_build_private/file_prefix_map_test.h" ]
	sources = get_target_outputs(":generate_file_prefix_map_test_source")
	deps = [ ":generate_file_prefix_map_test_source" ]

	_source_path = rebase_path(sources[0], root_build_dir)

	# The source file is prefixed with out/ since it's generated.
	defines = _path_test_define +
	[ "PW_BUILD_EXPECTED_SOURCE_PATH=\"out/$_source_path\"" ]
	include_dirs = [ "." ] # Allow accessing file_prefix_map_test.h
	visibility = [ ":*" ]
	}

	pw_source_set("empty_main") {
	sources = [ "empty_main.cc" ]
	visibility = [ ":*" ]
	}

	pw_test_group("tests") {
	tests = [
	":cc_blob_library_test",
	":file_prefix_map_test",
	]
	}
	}