From 7005bac8be02b5de1812f83d266da123937d2269 Mon Sep 17 00:00:00 2001
From: Tristan Ross <tristan.ross@midstall.com>
Date: Mon, 14 Apr 2025 19:15:49 -0700
Subject: [PATCH] docs: add toolchains and llvm

---
 doc/manual.md.in               |  1 +
 doc/redirects.json             | 15 +++++++++++++++
 doc/toolchains.md              |  5 +++++
 doc/toolchains/llvm.chapter.md | 35 ++++++++++++++++++++++++++++++++++
 4 files changed, 56 insertions(+)
 create mode 100644 doc/toolchains.md
 create mode 100644 doc/toolchains/llvm.chapter.md

diff --git a/doc/manual.md.in b/doc/manual.md.in
index 07e587190d84..160c6eaead3c 100644
--- a/doc/manual.md.in
+++ b/doc/manual.md.in
@@ -9,6 +9,7 @@ preface.chapter.md
 using-nixpkgs.md
 lib.md
 stdenv.md
+toolchains.md
 build-helpers.md
 development.md
 contributing.md
diff --git a/doc/redirects.json b/doc/redirects.json
index 3d4b4a4c084e..12d56f141bf9 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -5,6 +5,9 @@
   "chap-release-notes": [
     "release-notes.html#chap-release-notes"
   ],
+  "chap-toolchains": [
+    "index.html#chap-toolchains"
+  ],
   "cmake-ctest": [
     "index.html#cmake-ctest"
   ],
@@ -66,6 +69,9 @@
   "pkgs-replacevarswith": [
     "index.html#pkgs-replacevarswith"
   ],
+  "part-toolchains": [
+    "index.html#part-toolchains"
+  ],
   "preface": [
     "index.html#preface"
   ],
@@ -99,6 +105,12 @@
   "sec-build-helper-extendMkDerivation": [
     "index.html#sec-build-helper-extendMkDerivation"
   ],
+  "sec-building-packages-with-llvm": [
+    "index.html#sec-building-packages-with-llvm"
+  ],
+  "sec-building-packages-with-llvm-using-clang-stdenv": [
+    "index.html#sec-building-packages-with-llvm-using-clang-stdenv"
+  ],
   "sec-inkscape": [
     "index.html#sec-inkscape"
   ],
@@ -360,6 +372,9 @@
   "chap-stdenv": [
     "index.html#chap-stdenv"
   ],
+  "sec-using-llvm": [
+    "index.html#sec-using-llvm"
+  ],
   "sec-using-stdenv": [
     "index.html#sec-using-stdenv"
   ],
diff --git a/doc/toolchains.md b/doc/toolchains.md
new file mode 100644
index 000000000000..378f0b053c17
--- /dev/null
+++ b/doc/toolchains.md
@@ -0,0 +1,5 @@
+# Toolchains {#part-toolchains}
+
+```{=include=} chapters
+toolchains/llvm.chapter.md
+```
diff --git a/doc/toolchains/llvm.chapter.md b/doc/toolchains/llvm.chapter.md
new file mode 100644
index 000000000000..5f510c7cc25d
--- /dev/null
+++ b/doc/toolchains/llvm.chapter.md
@@ -0,0 +1,35 @@
+# The LLVM Toolchain {#chap-toolchains}
+
+LLVM is a target-independent optimizer and code generator and serves as the basis for many compilers such as Haskell's GHC, rustc, Zig, and many others. It forms the base tools for Apple's Darwin platform.
+
+## Using LLVM {#sec-using-llvm}
+
+LLVM has two ways of being used. One is by using it across all of Nixpkgs and the other is to compile and build individual packages.
+
+### Building packages with LLVM {#sec-building-packages-with-llvm}
+
+Nixpkgs supports two methods of compiling the world with LLVM. One is via setting `useLLVM` in `crossSystem` while importing. This is the recommended way when cross compiling as it is more expressive. An example of doing `aarch64-linux` cross compilation from `x86_64-linux` with LLVM on the target is the following:
+
+```nix
+import <nixpkgs> {
+  localSystem = {
+    system = "x86_64-linux";
+  };
+  crossSystem = {
+    useLLVM = true;
+    linker = "lld";
+  };
+}
+```
+
+Note that we set `linker` to `lld`. This is because LLVM has its own linker called "lld". By setting it, we utilize Clang and lld within this new instance of Nixpkgs. There is a shorthand method for building everything with LLVM: `pkgsLLVM`. This is easier to use with `nix-build` (or `nix build`):
+
+```bash
+nix-build -A pkgsLLVM.hello
+```
+
+This will compile the GNU hello package with LLVM and the lld linker like previously mentioned.
+
+#### Using `clangStdenv` {#sec-building-packages-with-llvm-using-clang-stdenv}
+
+Another simple way is to override the stdenv with `clangStdenv`. This causes a single package to be built with Clang. However, this `stdenv` does not override platform defaults to use compiler-rt, libc++, and libunwind. This is the preferred way to make a single package in Nixpkgs build with Clang. There are cases where just Clang isn't enough. For these situations, there is `libcxxStdenv`, which uses Clang with libc++ and compiler-rt.