gcc-wrapper: comment on alternate setup hook

We now have an alternate setup hook for gcc-wrapper that uses -I to add
include paths rather than -isystem. The latter flag can change the
search order specified by the build system. For KDE 5 packages, we don't
want that!

pkgs/build-support/gcc-wrapper/setup-hook-stdinc.sh

@@ -1,3 +1,9 @@
+# This is an alternate setup hook for gcc-wrapper that uses the -I flag to
+# add include search paths instead of -isystem. We need this for some packages
+# because -isystem can change the search order specified by prior -I flags.
+# Changing the search order can point gcc to the wrong package's headers.
+# The -I flag will never change the order of prior flags.
+
 export NIX_CC=@out@
 
 addCVars () {

pkgs/top-level/all-packages.nix

@@ -4089,6 +4089,15 @@ let
       inherit stdenv gcc binutils libc shell name cross;
     });
 
+  /* Alternative GCC wrapper that uses the standard -I include flag instead of
+   * -isystem. The -isystem flag can change the search order specified by prior
+   * -I flags. For KDE 5 packages, we don't want to interfere with the include
+   * search path order specified by the build system. Some packages depend on
+   * Qt 4 and Qt 5 simultaneously; because the two Qt versions provide headers
+   * with the same filenames, we must respect the search order specified by the
+   * build system so that the Qt 4 components find the Qt 4 headers and the Qt 5
+   * components find the Qt 5 headers.
+   */
   wrapGCCStdInc = glibc: baseGCC: (import ../build-support/gcc-wrapper) {
     nativeTools = stdenv.cc.nativeTools or false;
     nativeLibc = stdenv.cc.nativeLibc or false;