ci: support debugging IWYU in CI

Instead of requiring setting up a mock CI environment with the official
image locally. While such docs would be handy anyways, requiring that
entire setup to get a small piece of information from a build is
unnecessary.

.gitlab/ci/ctest_build.cmake

@@ -22,9 +22,32 @@ elseif (CTEST_CMAKE_GENERATOR MATCHES "Ninja")
   set(CTEST_BUILD_FLAGS "-l${nproc}")
 endif ()
 
+set(ctest_build_args)
+
+# IWYU debugging:
+# - set the name of the target (if not one of the main libraries)
+# - set the name of the source (without extension, relative to `Source/`)
+# - uncomment the debugging support in the relevant `configure_*_iwyu.cmake` file
+set(iwyu_source_target) # set for "other" targets not the "main" 3 libraries
+set(iwyu_source_name) # e.g., cmTarget
+if (iwyu_source_name AND "$ENV{CMAKE_CONFIGURATION}" MATCHES "iwyu")
+  if (NOT iwyu_source_target)
+    if (iwyu_source_name MATCHES "^(CTest/|cmCTest$)")
+      set(iwyu_source_target "CTestLib")
+    elseif (iwyu_source_name MATCHES "^CPack/")
+      set(iwyu_source_target "CPackLib")
+    else () # Assume everything else is in CMakeLib
+      set(iwyu_source_target "CMakeLib")
+    endif ()
+  endif ()
+  list(APPEND ctest_build_args
+    TARGET "Source/CMakeFiles/${iwyu_source_target}.dir/${iwyu_source_name}.cxx.o")
+endif ()
+
 ctest_build(
   NUMBER_WARNINGS num_warnings
-  RETURN_VALUE build_result)
+  RETURN_VALUE build_result
+  ${ctest_build_args})
 ctest_submit(PARTS Build)
 
 if (build_result)
@@ -37,6 +60,11 @@ if ("$ENV{CTEST_NO_WARNINGS_ALLOWED}" AND num_warnings GREATER 0)
     "Found ${num_warnings} warnings (treating as fatal).")
 endif ()
 
+if (ctest_build_args)
+  message(FATAL_ERROR
+    "Failing to prevent debugging support from being committed.")
+endif ()
+
 if (NOT "$ENV{CMAKE_CI_NO_INSTALL}")
   ctest_build(APPEND
     TARGET install