C++ compilation: flag for header-validation debug

Add the --[no]experimental_header_validation_debug
flag.

This flag tells Bazel to print extra debugging
information when a C++ compilation action fails
header inclusion validation.

We will enable this flag on BuildKite in hopes of
catching the culprit of bazelbuild#6847.

After we find the culprit, this commit should be
reverted and the
--experimental_header_validation_debug flag from
BuildKite's configuration should be removed.

See bazelbuild#6847

src/main/java/com/google/devtools/build/lib/rules/cpp/CppCompileAction.java

@@ -92,8 +92,6 @@ public class CppCompileAction extends AbstractAction
 
   private static final PathFragment BUILD_PATH_FRAGMENT = PathFragment.create("BUILD");
 
-  private static final boolean VALIDATION_DEBUG_WARN = false;
-
   protected final Artifact outputFile;
   private final Artifact sourceFile;
   private final CppConfiguration cppConfiguration;
@@ -814,27 +812,31 @@ public void validateInclusions(
         errors.add(input.getExecPath().toString());
       }
     }
-    if (VALIDATION_DEBUG_WARN) {
-      synchronized (System.err) {
+    if (cppConfiguration.getHeaderValidationDebug()) {
+      StringBuilder sb = new StringBuilder();
+      if (errors.hasProblems()) {
         if (errors.hasProblems()) {
-          if (errors.hasProblems()) {
-            System.err.println("ERROR: Include(s) were not in declared srcs:");
-          } else {
-            System.err.println("INFO: Include(s) were OK for '" + getSourceFile()
-                + "', declared srcs:");
-          }
-          for (Artifact a : ccCompilationContext.getDeclaredIncludeSrcs()) {
-            System.err.println("  '" + a.toDetailString() + "'");
-          }
-          System.err.println(" or under declared dirs:");
-          for (PathFragment f : Sets.newTreeSet(ccCompilationContext.getDeclaredIncludeDirs())) {
-            System.err.println("  '" + f + "'");
-          }
-          System.err.println(" with prefixes:");
-          for (PathFragment dirpath : ccCompilationContext.getQuoteIncludeDirs()) {
-            System.err.println("  '" + dirpath + "'");
-          }
+          sb.append("ERROR: Include(s) were NOT OK for '");
+        } else {
+          sb.append("INFO: Include(s) were OK for '");
         }
+        sb.append(getSourceFile()).append("', declared srcs:\n");
+        for (Artifact a : ccCompilationContext.getDeclaredIncludeSrcs()) {
+          sb.append("  '").append(a.toDetailString()).append("'\n");
+        }
+        sb.append(" declared dirs:\n");
+        for (PathFragment f : Sets.newTreeSet(ccCompilationContext.getDeclaredIncludeDirs())) {
+          sb.append("  '").append(f).append("'\n");
+        }
+        sb.append(" with prefixes:\n");
+        for (PathFragment dirpath : ccCompilationContext.getQuoteIncludeDirs()) {
+          sb.append("  '").append(dirpath).append("'\n");
+        }
+      }
+
+      String sbString = sb.toString();
+      synchronized (System.err) {
+        System.err.println(sbString);
       }
     }
     errors.assertProblemFree(this, getSourceFile());

src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java

@@ -553,6 +553,10 @@ public boolean disableDepsetInUserFlags() {
     return cppOptions.disableDepsetInUserFlags;
   }
 
+  public boolean getHeaderValidationDebug() {
+    return cppOptions.headerValidationDebug;
+  }
+
   public static PathFragment computeDefaultSysroot(String builtInSysroot) {
     if (builtInSysroot.isEmpty()) {
       return null;

src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java

@@ -797,6 +797,17 @@ public Label getFdoPrefetchHintsLabel() {
       help = "If enabled, cpu transformer is not used for CppConfiguration")
   public boolean doNotUseCpuTransformer;
 
+  // TODO(laszlocsomor): revert the commit that added this flag, after we found the root cause of
+  // https://github.com/bazelbuild/bazel/issues/6847
+  @Option(
+      name = "experimental_header_validation_debug",
+      defaultValue = "false",
+      documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
+      effectTags = {OptionEffectTag.EXECUTION},
+      metadataTags = {OptionMetadataTag.EXPERIMENTAL},
+      help = "If enabled, CppCompileAction prints extra info about failed header validation.")
+  public boolean headerValidationDebug;
+
   @Override
   public FragmentOptions getHost() {
     CppOptions host = (CppOptions) getDefault();