cc-wrapper: comment explaining C++ stdlib order

There is context here that I needed when resolving an issue in which
libc was added to NIX_CFLAGS_COMPILE before the C++ stdlib that took
me awhile to understand.

It was suggested to me that this context be included as a comment,
since it is not obvious and could help others in the future.

1 files changed, 25 insertions, 0 deletions

diff --git a/pkgs/build-support/cc-wrapper/cc-wrapper.sh b/pkgs/build-support/cc-wrapper/cc-wrapper.sh
index 83b6817798f2..78759f2cfbbc 100644
--- a/pkgs/build-support/cc-wrapper/cc-wrapper.sh
+++ b/pkgs/build-support/cc-wrapper/cc-wrapper.sh
@@ -122,6 +122,31 @@ fi
 
 if [[ "$isCxx" = 1 ]]; then
     if [[ "$cxxInclude" = 1 ]]; then
+        #
+        # The motivation for this comment is to explain the reason for appending
+        # the C++ stdlib to NIX_CFLAGS_COMPILE, which I initially thought should
+        # change and later realized it shouldn't in:
+        #
+        #   https://github.com/NixOS/nixpkgs/pull/185569#issuecomment-1234959249
+        #
+        # NIX_CFLAGS_COMPILE contains dependencies added using "-isystem", and
+        # NIX_CXXSTDLIB_COMPILE adds the C++ stdlib using "-isystem". Appending
+        # NIX_CXXSTDLIB_COMPILE to NIX_CLAGS_COMPILE emulates this part of the
+        # include lookup order from GCC/Clang:
+        #
+        # > 4. Directories specified with -isystem options are scanned in
+        # >    left-to-right order.
+        # > 5. Standard system directories are scanned.
+        # > 6. Directories specified with -idirafter options are scanned
+        # >    in left-to-right order.
+        #
+        # NIX_CXX_STDLIB_COMPILE acts as the "standard system directories" that
+        # are otherwise missing from CC in nixpkgs, so should be added last.
+        #
+        # This means that the C standard library should never be present inside
+        # NIX_CFLAGS_COMPILE, because it MUST come after the C++ stdlib. It is
+        # added automatically by cc-wrapper later using "-idirafter".
+        #
         NIX_CFLAGS_COMPILE_@suffixSalt@+=" $NIX_CXXSTDLIB_COMPILE_@suffixSalt@"
     fi
     if [[ "$cxxLibrary" = 1 ]]; then