From cdb5d3a13cf1ceb8b411ff5bd821cd223a4440fe Mon Sep 17 00:00:00 2001
From: Randy Eckenrode <randy@largeandhighquality.com>
Date: Sat, 12 Apr 2025 16:46:01 -0400
Subject: [PATCH] doc/stdenv/platform-notes: add section about libc++

---
 doc/redirects.json                   |  6 ++++++
 doc/stdenv/platform-notes.chapter.md | 17 +++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/doc/redirects.json b/doc/redirects.json
index 1230b6460b54..4b5484f5b5c3 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -216,6 +216,12 @@
   "sec-building-packages-with-llvm-using-clang-stdenv": [
     "index.html#sec-building-packages-with-llvm-using-clang-stdenv"
   ],
+  "sec-darwin-libcxx-deployment-targets": [
+    "index.html#sec-darwin-libcxx-deployment-targets"
+  ],
+  "sec-darwin-libcxx-versions": [
+    "index.html#sec-darwin-libcxx-versions"
+  ],
   "sec-functions-library-treefmt": [
     "index.html#sec-functions-library-treefmt"
   ],
diff --git a/doc/stdenv/platform-notes.chapter.md b/doc/stdenv/platform-notes.chapter.md
index f7e9b4fcc351..06662bbc76fa 100644
--- a/doc/stdenv/platform-notes.chapter.md
+++ b/doc/stdenv/platform-notes.chapter.md
@@ -12,6 +12,9 @@ If it does, you’re done; skip the rest of this.
 - Darwin uses Clang by default instead of GCC. Packages that refer to `$CC` or `cc` should just work in most cases.
   Some packages may hardcode `gcc` or `g++`. You can usually fix that by setting `makeFlags = [ "CC=cc" "CXX=C++" ]`.
   If that does not work, you will have to patch the build scripts yourself to use the correct compiler for Darwin.
+- Darwin uses the system libc++ by default to avoid ODR violations and potential compatibility issues from mixing LLVM libc++ with the system libc++.
+  While mixing the two usually worked, the two implementations are not guaranteed to be ABI compatible and are considered distinct by upstream.
+  See the troubleshooting guide below if you need to use newer C++ library features than those supported by the default deployment target.
 - Darwin needs an SDK to build software.
   The SDK provides a default set of frameworks and libraries to build software, most of which are specific to Darwin.
   There are multiple versions of the SDK packages in Nixpkgs, but one is included by default in the `stdenv`.
@@ -30,6 +33,20 @@ If you run into issues or failures, continue reading below for how to deal with
 
 ### Darwin Issue Troubleshooting {#sec-darwin-troubleshooting}
 
+#### Building a C++ package or library says that certain APIs are unavailable {#sec-darwin-libcxx-versions}
+
+While some newer APIs may be available via headers only, some require using a system libc++ with the required API support.
+When that happens, your build will fail because libc++ makes failure to use the correct deployment target an error.
+To make the newer API available, increase the deployment target to the required version.
+Note that it is possible to use libc++ from LLVM instead of increasing the deployment target, but it is not recommended.
+Doing so can cause problems when multiple libc++ implementations are linked into a binary (e.g., from dependencies).
+
+##### Using a newer deployment target {#sec-darwin-libcxx-deployment-targets}
+
+See below for how to use a newer deployment target.
+For example, `std::print` depends on features that are only available on macOS 13.3 or newer.
+To make them available, set the deployment target to 13.3 using `darwinMinVersionHook`.
+
 #### Package requires a non-default SDK or fails to build due to missing frameworks or symbols {#sec-darwin-troubleshooting-using-sdks}
 
 In some cases, you may have to use a non-default SDK.