Document that libc++ is the only supported STL, and why.

Bug: 372852985
Change-Id: I479897e5c9b98816ea8c34b00d310877631120fe
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5982007
Auto-Submit: Peter Kasting <pkasting@chromium.org>
Commit-Queue: Peter Kasting <pkasting@chromium.org>
Reviewed-by: danakj <danakj@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1376565}

docs/contributing.md

@@ -400,17 +400,18 @@ general rules of thumb can be helpful in navigating how to structure changes:
   product in the Chromium repositories that depends on that line of code or else
   the line of code should be removed.
 
-  When you are adding support for a new OS, a new architecture, a new port or
-  a new top-level directory, please send an email to
-  chrome-atls@google.com and get approval. For long-term maintenance
+  When you are adding support for a new OS, architecture, compiler/STL
+  implementation, platform, or simply a new top-level directory, please send an
+  email to chrome-atls@google.com and get approval. For long-term maintenance
   reasons, we will accept only things that are used by the Chromium project
   (including Chromium-supported projects like V8 and Skia) and things whose
   benefit to Chromium outweighs any cost increase in maintaining Chromium's
-  supported architectures / platforms (e.g. adding one ifdef branch for an
-  unsupported architecture / platform has negligible cost and is likely fine,
+  supported toolchains, architectures, and platforms (e.g. adding one ifdef
+  branch for an unsupported architecture has negligible cost and is likely fine,
   but introducing new abstractions or changes to higher level directories has
   a high cost and would need to provide Chromium with corresponding benefit).
-  Note that an unsupported architecture / platform will not have bots on
+  See the [documentation on toolchain support](toolchain_support.md) for more
+  details. Note that an unsupported configuration will not have bots on
   Google-managed waterfalls (even FYI bots) or maintained by Chromium
   developers. Please use existing ifdef branches as much as possible.
 

docs/linux/build_instructions.md

@@ -21,6 +21,10 @@ Are you a Google employee? See
     to a Python v3.8+ binary). Depot_tools bundles an appropriate version
     of Python in `$depot_tools/python-bin`, if you don't have an appropriate
     version already on your system.
+* `libc++` is currently the only supported STL. `clang` is the only
+  officially-supported compiler, though external community members generally
+  keep things building with `gcc`. For more details, see the
+  [supported toolchains doc](../toolchain_support.md).
 
 Most development is done on Ubuntu (Chromium's build infrastructure currently
 runs 22.04, Jammy Jellyfish). There are some instructions for other distros

docs/toolchain_support.md

@@ -1,15 +1,40 @@
 Configurations supported by the toolchain team
 ==============================================
 
-This document describes considerations to follow when adding a new build
-config. A build config is something like a new compiler / linker configuration,
-a new test binary, a new `target_os`, a new `target_cpu`, etc.
+This document describes the existing supported build configs, and considerations
+to follow when adding a new one. A build config is something like a new compiler
+/ linker configuration, a new test binary, a new `target_os`, a new
+`target_cpu`, etc.
 
-Background
-----------
+Existing toolchain support
+--------------------------
+
+Chromium prioritizes user benefits (safety, performance) and maintainability
+over theoretical purity (e.g. standards compliance for its own sake). Currently,
+the best way to achieve those goals is to support a single compiler (`clang`)
+and STL implementation (`libc++`).
+* We use clang-specific extensions (e.g. the
+  `[[clang::lifetimebound]]` C++ attribute)
+* We rely on guarantees in libc++ beyond what the STL requires (e.g.
+  deterministically crashing for certain cases of UB; having a
+  trivially-relocatable `std::string` implementation)
+
+Even within clang/libc++, we often rely on recent bugfixes and feature
+additions, so generally only the most recent LLVM version is supported. Building
+Chromium with an unsupported toolchain will fail to compile at best; at worst,
+it will compile, but have bugs, security holes, or reduced performance.
+
+We currently allow community-contributed patches that support building with gcc,
+since this is a requirement for many Linux environments and can be accommodated
+without much maintainability cost or risk of introducing unsafe behavior. As of
+M138, however, even gcc builds will only work with libc++.
+
+Toolchain updates
+-----------------
 
 We update our toolchain (the C/C++/Objective-C compiler `clang`, the linker
-`lld`, and a small assortment of helper binaries) every 2-4 weeks.
+`lld`, the STL implementation `libc++`, and a small assortment of helper
+binaries) every 2-4 weeks.
 
 This toolchain is used to build Chromium for **7+ platforms** (Android,
 Chromecast, Chrome OS, Fuchsia, iOS, Linux, macOS, Windows) targeting
@@ -31,7 +56,6 @@ opt-in trybots.
 The toolchain team has established contacts to most platform owners in
 Chromium, so that we can ask for help quickly when needed.
 
-
 Toolchain guarantees
 --------------------
 
@@ -48,7 +72,6 @@ covered on the CQ, **we won't revert toolchain updates**. We will do our best
 to fix things quickly (see below for how to file a good bug) and to fix forward
 to get you unblocked.
 
-
 Talk to the toolchain team to make sure your new config is supported
 --------------------------------------------------------------------