pw_build: Document build_dir requirements

Due to b/278898014 and b/278906020, there will be issues if using a GN
build directory that is more than one directory away from the project
root. This adds documentation to `pw_build` and the
`getting_started.rst` to ensure this is currently documented until the
LLVM fix can land upstream and Pigweed can do an LLVM roll.

Tested: `pw watch --serve-docs`.
Bug: b/278906020
Change-Id: Ifac9bbe53f2f7ce1e4ca54c1c346c110353042f5
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/139951
Reviewed-by: Carlos Chinchilla <cachinchilla@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Gulfem Savrun Yeniceri <gulfem@google.com>
Pigweed-Auto-Submit: Greg Pataky <gregpataky@google.com>

docs/getting_started.rst

@@ -228,9 +228,20 @@ Run GN as seen below:
 
   $ gn gen out
 
-Note that ``out`` is simply the directory the build files are saved to. Unless
-this directory is deleted or you desire to do a clean build, there's no need to
-run GN again; just rebuild using Ninja directly.
+.. note::
+  ``out`` is simply the directory the build files are saved to. Unless
+  this directory is deleted or you desire to do a clean build, there's no need
+  to run GN again; just rebuild using Ninja directly.
+
+.. warning::
+  Unless your build directory (the ``out`` in ``gn gen out``) is exactly one
+  directory away from the project root directory (the Pigweed repo root in this
+  case), there will be issues finding source files while debugging and while
+  generating coverage reports. This is due an issue in upstream LLVM reordering
+  debug and coverage path mappings (tracked by
+  `b/278898014 <https://issuetracker.google.com/278898014>`_ and
+  `b/278906020 <https://issuetracker.google.com/278906020>`_). **We recommend
+  sticking to simple, single directory build directories for the time being.**
 
 Now that we have build files, it's time to build Pigweed!
 

pw_build/BUILD.gn

@@ -237,7 +237,25 @@ config("toolchain_cpp_standard") {
 # 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. Clang and GCC apply these in opposite order.
+  # 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/",