From bc2b4e77d888ff13effd7b244c37dc135bbc9b7c Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <silvan.mosberger@moduscreate.com>
Date: Tue, 22 Apr 2025 16:56:40 +0200
Subject: [PATCH] llvmPackages: add comments for all patches in LLVM and CLang

Co-Authored-By: Silvan Mosberger <silvan.mosberger@moduscreate.com>
---
 .../compilers/llvm/common/clang/default.nix       |  4 ++++
 .../compilers/llvm/common/llvm/default.nix        | 15 +++++++++++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/pkgs/development/compilers/llvm/common/clang/default.nix b/pkgs/development/compilers/llvm/common/clang/default.nix
index c5565ca405b8..8a65d5750d53 100644
--- a/pkgs/development/compilers/llvm/common/clang/default.nix
+++ b/pkgs/development/compilers/llvm/common/clang/default.nix
@@ -48,6 +48,7 @@ stdenv.mkDerivation (
     patches =
       [
         (getVersionFile "clang/purity.patch")
+        # Remove extraneous ".a" suffix from baremetal clang_rt.builtins when compiling for baremetal.
         # https://reviews.llvm.org/D51899
         (getVersionFile "clang/gnu-install-dirs.patch")
       ]
@@ -76,6 +77,7 @@ stdenv.mkDerivation (
         else
           ./ignore-nostd-link-13.diff
       )
+      # Pass the correct path to libllvm
       ++ [
         (replaceVars
           (
@@ -112,6 +114,8 @@ stdenv.mkDerivation (
             stripLen = 1;
             hash = "sha256-Vs32kql7N6qtLqc12FtZHURcbenA7+N3E/nRRX3jdig=";
           })
+      # Fixes a bunch of lambda-related crashes
+      # https://github.com/llvm/llvm-project/pull/93206
       ++ lib.optional (lib.versions.major release_version == "18") (fetchpatch {
         name = "tweak-tryCaptureVariable-for-unevaluated-lambdas.patch";
         url = "https://github.com/llvm/llvm-project/commit/3d361b225fe89ce1d8c93639f27d689082bd8dad.patch";
diff --git a/pkgs/development/compilers/llvm/common/llvm/default.nix b/pkgs/development/compilers/llvm/common/llvm/default.nix
index d2f9e711f653..d9a6f8087496 100644
--- a/pkgs/development/compilers/llvm/common/llvm/default.nix
+++ b/pkgs/development/compilers/llvm/common/llvm/default.nix
@@ -123,8 +123,14 @@ stdenv.mkDerivation (
     ];
 
     patches =
-      lib.optional (lib.versionOlder release_version "14") ./llvm-config-link-static.patch
+      lib.optional (lib.versionOlder release_version "14")
+        # When cross-compiling we configure llvm-config-native with an approximation
+        # of the flags used for the normal LLVM build. To avoid the need for building
+        # a native libLLVM.so (which would fail) we force llvm-config to be linked
+        # statically against the necessary LLVM components always.
+        ./llvm-config-link-static.patch
       ++ lib.optionals (lib.versions.major release_version == "12") [
+        # Fix llvm being miscompiled by some gccs. See https://github.com/llvm/llvm-project/issues/49955
         (getVersionFile "llvm/fix-llvm-issue-49955.patch")
 
         # On older CPUs (e.g. Hydra/wendy) we'd be getting an error in this test.
@@ -135,6 +141,9 @@ stdenv.mkDerivation (
           stripLen = 1;
         })
       ]
+      # Support custom installation dirs
+      # Originally based off https://reviews.llvm.org/D99484
+      # Latest state: https://github.com/llvm/llvm-project/pull/125376
       ++ [ (getVersionFile "llvm/gnu-install-dirs.patch") ]
       ++ lib.optionals (lib.versionAtLeast release_version "15") [
         # Running the tests involves invoking binaries (like `opt`) that depend on
@@ -241,7 +250,8 @@ stdenv.mkDerivation (
           ]
       ++
         lib.optional (lib.versions.major release_version == "17")
-          # resolves https://github.com/llvm/llvm-project/issues/75168
+          # Fixes a crash with -fzero-call-used-regs=used-gpr
+          # See also https://github.com/llvm/llvm-project/issues/75168
           (
             fetchpatch {
               name = "fix-fzero-call-used-regs.patch";
@@ -278,6 +288,7 @@ stdenv.mkDerivation (
             })
           ]
       ++ lib.optionals enablePolly [
+        # Just like the `gnu-install-dirs` patch, but for `polly`.
         (getVersionFile "llvm/gnu-install-dirs-polly.patch")
       ]
       ++