[Driver] -include: deprecate probing .gch (llvm#67084)

`-include a.h` probes `a.h.pch` and `a.h.gch`, if not found, falls back to
`a.h`. `.pch` is the preferred extension name. Probing .gch is supposed to
provide compatibility with build systems that do
```
clang -x c-header a.h -o out/a.h.gch
clang -include out/a.h -c a.c  # out/a.h.gch is present while out/a.h is absent
```
(not sure what projects actually do this with Clang)

But it can often get in the way [^0][^1][^2] when GCC and Clang are mixed as the file
format is incompatible with GCC's. Let's deprecate .gch probing.
Some tests using `-include` are switched to `.pch`.
`test/PCH/pch-dir.c` shows the -Wdeprecated warning.

[^0]: https://discourse.llvm.org/t/how-to-have-clang-ignore-gch-directories/51835
[^1]: https://bugreports.qt.io/browse/QTCREATORBUG-22427
[^2]: https://gitlab.kitware.com/cmake/cmake/-/issues/22081

Author: MaskRay

clang/docs/ReleaseNotes.rst

@@ -43,6 +43,8 @@ C/C++ Language Potentially Breaking Changes
 
 - The default extension name for PCH generation (``-c -xc-header`` and ``-c
   -xc++-header``) is now ``.pch`` instead of ``.gch``.
+- ``-include a.h`` probing ``a.h.gch`` is deprecated. Change the extension name
+  to ``.pch`` or use ``-include-pch a.h.gch``.
 
 C++ Specific Potentially Breaking Changes
 -----------------------------------------

clang/include/clang/Basic/DiagnosticDriverKinds.td

@@ -431,6 +431,9 @@ def warn_drv_overriding_option : Warning<
 def warn_drv_treating_input_as_cxx : Warning<
   "treating '%0' input as '%1' when in C++ mode, this behavior is deprecated">,
   InGroup<Deprecated>;
+def warn_drv_include_probe_gch : Warning<
+  "'%0' probing .gch is deprecated. Use '-include-pch %1' or switch to .pch instead">,
+  InGroup<Deprecated>;
 def warn_drv_pch_not_first_include : Warning<
   "precompiled header '%0' was ignored because '%1' is not first '-include'">;
 def warn_missing_sysroot : Warning<"no such sysroot directory: '%0'">,

clang/lib/Driver/ToolChains/Clang.cpp

@@ -1284,6 +1284,7 @@ void Clang::AddPreprocessingOptions(Compilation &C, const JobAction &JA,
         llvm::sys::path::replace_extension(P, "gch");
         if (D.getVFS().exists(P)) {
           FoundPCH = true;
+          D.Diag(diag::warn_drv_include_probe_gch) << A->getAsString(Args) << P;
         }
       }
 

clang/test/ClangScanDeps/Inputs/modules-pch-common-submodule/cdb_pch.json

@@ -1,7 +1,7 @@
 [
   {
     "directory": "DIR",
-    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.gch",
+    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.pch",
     "file": "DIR/pch.h"
   }
 ]

clang/test/ClangScanDeps/Inputs/modules-pch-common-via-submodule/cdb_pch.json

@@ -1,7 +1,7 @@
 [
   {
     "directory": "DIR",
-    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.gch",
+    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.pch",
     "file": "DIR/pch.h"
   }
 ]

clang/test/ClangScanDeps/Inputs/modules-pch/cdb_pch.json

@@ -1,7 +1,7 @@
 [
   {
     "directory": "DIR",
-    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.gch",
+    "command": "clang -x c-header DIR/pch.h -fmodules -gmodules -fimplicit-module-maps -fmodules-cache-path=DIR/cache -o DIR/pch.h.pch",
     "file": "DIR/pch.h"
   }
 ]

clang/test/ClangScanDeps/modules-pch-common-submodule.c

@@ -94,7 +94,7 @@
 // CHECK-TU:            ],
 // CHECK-TU:            "file-deps": [
 // CHECK-TU-NEXT:         "[[PREFIX]]/tu.c",
-// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.gch"
+// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.pch"
 // CHECK-TU-NEXT:       ],
 // CHECK-TU-NEXT:       "input-file": "[[PREFIX]]/tu.c"
 // CHECK-TU-NEXT:     }

clang/test/ClangScanDeps/modules-pch-common-via-submodule.c

@@ -91,7 +91,7 @@
 // CHECK-TU:            ],
 // CHECK-TU:            "file-deps": [
 // CHECK-TU-NEXT:         "[[PREFIX]]/tu.c",
-// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.gch"
+// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.pch"
 // CHECK-TU-NEXT:       ],
 // CHECK-TU-NEXT:       "input-file": "[[PREFIX]]/tu.c"
 // CHECK-TU-NEXT:     }

clang/test/ClangScanDeps/modules-pch.c

@@ -14,7 +14,7 @@
 // RUN: cat %t/result_pch.json | sed 's:\\\\\?:/:g' | FileCheck %s -DPREFIX=%/t -check-prefix=CHECK-PCH
 //
 // Check we didn't build the PCH during dependency scanning.
-// RUN: not cat %/t/pch.h.gch
+// RUN: not cat %/t/pch.h.pch
 //
 // CHECK-PCH:      {
 // CHECK-PCH-NEXT:   "modules": [
@@ -129,7 +129,7 @@
 // CHECK-TU:            ],
 // CHECK-TU:            "file-deps": [
 // CHECK-TU-NEXT:         "[[PREFIX]]/tu.c",
-// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.gch"
+// CHECK-TU-NEXT:         "[[PREFIX]]/pch.h.pch"
 // CHECK-TU-NEXT:       ],
 // CHECK-TU-NEXT:       "input-file": "[[PREFIX]]/tu.c"
 // CHECK-TU-NEXT:     }
@@ -179,7 +179,7 @@
 // CHECK-TU-WITH-COMMON:            ],
 // CHECK-TU-WITH-COMMON:            "file-deps": [
 // CHECK-TU-WITH-COMMON-NEXT:         "[[PREFIX]]/tu_with_common.c",
-// CHECK-TU-WITH-COMMON-NEXT:         "[[PREFIX]]/pch.h.gch"
+// CHECK-TU-WITH-COMMON-NEXT:         "[[PREFIX]]/pch.h.pch"
 // CHECK-TU-WITH-COMMON-NEXT:       ],
 // CHECK-TU-WITH-COMMON-NEXT:       "input-file": "[[PREFIX]]/tu_with_common.c"
 // CHECK-TU-WITH-COMMON-NEXT:     }

clang/test/Index/cindex-from-source.m

@@ -1,5 +1,5 @@
 // REQUIRES: native
-// RUN: c-index-test -write-pch %t.pfx.h.gch -x objective-c-header %S/Inputs/cindex-from-source.h
+// RUN: c-index-test -write-pch %t.pfx.h.pch -x objective-c-header %S/Inputs/cindex-from-source.h
 // RUN: c-index-test -test-load-source local %s -include %t.pfx.h > %t
 // RUN: FileCheck %s < %t
 // CHECK: cindex-from-source.m:{{.*}}:{{.*}}: StructDecl=s0:{{.*}}:{{.*}}