[Caching] Put caching diagnostics into its own DiagnosticGroups (#82507)

Add explanation and documentation for swift caching diagnostics.

rdar://154335823

<!--
If this pull request is targeting a release branch, please fill out the
following form:

https://github.com/swiftlang/.github/blob/main/PULL_REQUEST_TEMPLATE/release.md?plain=1

Otherwise, replace this comment with a description of your changes and
rationale. Provide links to external references/discussions if
appropriate.
If this pull request resolves any GitHub issues, link them like so:

  Resolves <link to issue>, resolves <link to another issue>.

For more information about linking a pull request to an issue, see:

https://docs.github.com/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
-->

<!--
Before merging this pull request, you must run the Swift continuous
integration tests.
For information about triggering CI builds via @swift-ci, see:

https://github.com/apple/swift/blob/main/docs/ContinuousIntegration.md#swift-ci

Thank you for your contribution to Swift!
-->

---------

Co-authored-by: Allan Shortlidge <[email protected]>

Author: cachemeifyoucan

include/swift/AST/DiagnosticGroups.def

@@ -71,6 +71,7 @@ GROUP(StringInterpolationConformance, "string-interpolation-conformance")
 GROUP(TemporaryPointers, "temporary-pointers")
 GROUP(TrailingClosureMatching, "trailing-closure-matching")
 GROUP(UnknownWarningGroup, "unknown-warning-group")
+GROUP(CompilationCaching, "compilation-caching")
 
 #define UNDEFINE_DIAGNOSTIC_GROUPS_MACROS
 #include "swift/AST/DefineDiagnosticGroupsMacros.h"

include/swift/AST/DiagnosticsFrontend.def

@@ -509,30 +509,30 @@ REMARK(matching_output_produced,none,
       "produced matching output file '%0' for deterministic check: hash '%1'", (StringRef, StringRef))
 
 // Caching related diagnostics
-ERROR(error_caching_no_cas_fs, none,
+GROUPED_ERROR(error_caching_no_cas_fs, CompilationCaching, none,
     "caching is enabled without CAS file-system options, input is not immutable", ())
 ERROR(error_prefix_mapping, none, "cannot create scanner prefix mapping: '%0'", (StringRef))
 
 REMARK(replay_output, none, "replay output file '%0': key '%1'", (StringRef, StringRef))
 REMARK(output_cache_miss, none, "cache miss for input file '%0': key '%1'", (StringRef, StringRef))
 
 // CAS related diagnostics
-ERROR(error_invalid_cas_id, none, "CAS cannot parse id '%0': %1", (StringRef, StringRef))
-ERROR(error_cas, none, "CAS error encountered during %0: %1", (StringRef, StringRef))
-ERROR(error_cas_fs_creation, none, "cannot create CAS filesystem: %0", (StringRef))
-ERROR(error_cache_key_creation, none, "cannot create cache key for compilation %0: %1", (StringRef, StringRef))
-ERROR(error_cas_file_ref, none, "cannot load file %0 from CAS filesystem", (StringRef))
-ERROR(error_cas_conflict_options, none, "cannot setup CAS due to conflicting '-cas-*' options", ())
-ERROR(error_cas_initialization, none, "CAS cannot be initialized from the specified '-cas-*' options: %0", (StringRef))
-ERROR(error_cas_malformed_input, none, "CAS input '%0' is malformed: %1", (StringRef, StringRef))
-WARNING(cache_replay_failed, none, "cache replay failed: %0", (StringRef))
-
-ERROR(error_failed_cached_diag, none, "failed to serialize cached diagnostics: %0", (StringRef))
-ERROR(error_replay_cached_diag, none, "failed to replay cached diagnostics: %0", (StringRef))
-
-ERROR(error_load_input_from_cas, none, "failed to load input '%0' from CAS", (StringRef))
-
-ERROR(error_wrong_input_num_for_input_file_key, none, "-input-file-key only support one input file", ())
+GROUPED_ERROR(error_invalid_cas_id, CompilationCaching, none, "CAS cannot parse id '%0': %1", (StringRef, StringRef))
+GROUPED_ERROR(error_cas, CompilationCaching, none, "CAS error encountered during %0: %1", (StringRef, StringRef))
+GROUPED_ERROR(error_cas_fs_creation, CompilationCaching, none, "cannot create CAS filesystem: %0", (StringRef))
+GROUPED_ERROR(error_cache_key_creation, CompilationCaching, none, "cannot create cache key for compilation %0: %1", (StringRef, StringRef))
+GROUPED_ERROR(error_cas_file_ref, CompilationCaching, none, "cannot load file %0 from CAS filesystem", (StringRef))
+GROUPED_ERROR(error_cas_conflict_options, CompilationCaching, none, "cannot setup CAS due to conflicting '-cas-*' options", ())
+GROUPED_ERROR(error_cas_initialization, CompilationCaching, none, "CAS cannot be initialized from the specified '-cas-*' options: %0", (StringRef))
+GROUPED_ERROR(error_cas_malformed_input, CompilationCaching, none, "CAS input '%0' is malformed: %1", (StringRef, StringRef))
+GROUPED_WARNING(cache_replay_failed, CompilationCaching, none, "cache replay failed: %0", (StringRef))
+
+GROUPED_ERROR(error_failed_cached_diag, CompilationCaching, none, "failed to serialize cached diagnostics: %0", (StringRef))
+GROUPED_ERROR(error_replay_cached_diag, CompilationCaching, none, "failed to replay cached diagnostics: %0", (StringRef))
+
+GROUPED_ERROR(error_load_input_from_cas, CompilationCaching, none, "failed to load input '%0' from CAS", (StringRef))
+
+GROUPED_ERROR(error_wrong_input_num_for_input_file_key, CompilationCaching, none, "-input-file-key only support one input file", ())
 
 // Dependency Verifier Diagnostics
 ERROR(missing_member_dependency,none,

userdocs/diagnostics/compilation-caching.md

@@ -0,0 +1,16 @@
+# Compilation Caching
+
+Compilation caching allows Swift compiler to reuse previously compiled outputs if the identical
+compilation has been done before.
+
+When compilation caching is enabled (via `-cache-compile-job` flag), the build commands are
+expected to be generated by Swift driver, and the command-line of compilation tasks contains
+CASIDs that are objects constructed during planning phase. These CAS objects need to be backed
+by CAS storage and in a specific scheme accepted by the compiler. Any malformed command-line
+will cause error in this category. If the inputs changed, always fallback to re-run `swiftc`
+command to plan the new build commands.
+
+The other category of error is unexpected failures when performing reads/writes to Content
+Addressable Storage. Please refer to the error message (contains errors provided by CAS storage) for clues.
+If the error persists, consider clearing the cache. To clear the cache, delete the directory
+pointed to by the `-cas-path` option. Note that the CAS directory should only be deleted as a whole when not used.