[NFC] Standardize dump() methods in frontend

By convention, most structs and classes in the Swift compiler include a `dump()` method which prints debugging information. This method is meant to be called only from the debugger, but this means they’re often unused and may be eliminated from optimized binaries. On the other hand, some parts of the compiler call `dump()` methods directly despite them being intended as a pure debugging aid. clang supports attributes which can be used to avoid these problems, but they’re used very inconsistently across the compiler.

This commit adds `SWIFT_DEBUG_DUMP` and `SWIFT_DEBUG_DUMPER(<name>(<params>))` macros to declare `dump()` methods with the appropriate set of attributes and adopts this macro throughout the frontend. It does not pervasively adopt this macro in SILGen, SILOptimizer, or IRGen; these components use `dump()` methods in a different way where they’re frequently called from debugging code. Nor does it adopt it in runtime components like swiftRuntime and swiftReflection, because I’m a bit worried about size.

Despite the large number of files and lines affected, this change is NFC.

Author: beccadax

docs/DebuggingTheCompiler.rst

@@ -214,6 +214,11 @@ debugging press <CTRL>-C on the LLDB prompt.
 Note that this only works in Xcode if the PATH variable in the scheme's
 environment setting contains the path to the dot tool.
 
+swift/Basic/Debug.h includes macros to help contributors declare these methods
+with the proper attributes to ensure they'll be available in the debugger. In
+particular, if you see ``SWIFT_DEBUG_DUMP`` in a class declaration, that class
+has a ``dump()`` method you can call.
+
 Debugging and Profiling on SIL level
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

include/swift/AST/ASTNode.h

@@ -18,6 +18,7 @@
 #define SWIFT_AST_AST_NODE_H
 
 #include "llvm/ADT/PointerUnion.h"
+#include "swift/Basic/Debug.h"
 #include "swift/AST/TypeAlignments.h"
 
 namespace llvm {
@@ -62,9 +63,7 @@ namespace swift {
     FUNC(Decl)
 #undef FUNC
 
-    LLVM_ATTRIBUTE_DEPRECATED(
-        void dump() const LLVM_ATTRIBUTE_USED,
-        "only for use within the debugger");
+    SWIFT_DEBUG_DUMP;
     void dump(llvm::raw_ostream &OS, unsigned Indent = 0) const;
 
     /// Whether the AST node is implicit.

include/swift/AST/ASTScope.h

@@ -32,6 +32,7 @@
 #include "swift/AST/NameLookup.h" // for DeclVisibilityKind
 #include "swift/AST/SimpleRequest.h"
 #include "swift/Basic/Compiler.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/Basic/NullablePtr.h"
 #include "swift/Basic/SourceManager.h"
@@ -330,8 +331,7 @@ class ASTScopeImpl {
   virtual NullablePtr<const void> addressForPrinting() const;
 
 public:
-  LLVM_ATTRIBUTE_DEPRECATED(void dump() const LLVM_ATTRIBUTE_USED,
-                            "only for use within the debugger");
+  SWIFT_DEBUG_DUMP;
 
   void dumpOneScopeMapLocation(std::pair<unsigned, unsigned> lineColumn);
 

include/swift/AST/AccessScope.h

@@ -15,6 +15,7 @@
 
 #include "swift/AST/AttrKind.h"
 #include "swift/AST/DeclContext.h"
+#include "swift/Basic/Debug.h"
 #include "llvm/ADT/PointerIntPair.h"
 
 namespace swift {
@@ -87,7 +88,7 @@ class AccessScope {
     return None;
   }
 
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
 };
 
 } // end namespace swift

include/swift/AST/AnyFunctionRef.h

@@ -14,6 +14,7 @@
 #define SWIFT_AST_ANY_FUNCTION_REF_H
 
 #include "swift/Basic/Compiler.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/AST/Decl.h"
 #include "swift/AST/Expr.h"
@@ -177,8 +178,7 @@ class AnyFunctionRef {
 #pragma warning(push)
 #pragma warning(disable: 4996)
 #endif
-  LLVM_ATTRIBUTE_DEPRECATED(void dump() const LLVM_ATTRIBUTE_USED,
-                            "only for use within the debugger") {
+  SWIFT_DEBUG_DUMP {
     if (auto afd = TheFunction.dyn_cast<AbstractFunctionDecl *>()) {
       return afd->dump();
     }

include/swift/AST/Attr.h

@@ -17,6 +17,7 @@
 #ifndef SWIFT_ATTR_H
 #define SWIFT_ATTR_H
 
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/InlineBitfield.h"
 #include "swift/Basic/SourceLoc.h"
 #include "swift/Basic/UUID.h"
@@ -1583,7 +1584,7 @@ class DeclAttributes {
   /// a declaration is deprecated on all deployment targets, or null otherwise.
   const AvailableAttr *getDeprecated(const ASTContext &ctx) const;
 
-  void dump(const Decl *D = nullptr) const;
+  SWIFT_DEBUG_DUMPER(dump(const Decl *D = nullptr));
   void print(ASTPrinter &Printer, const PrintOptions &Options,
              const Decl *D = nullptr) const;
   static void print(ASTPrinter &Printer, const PrintOptions &Options,

include/swift/AST/CaptureInfo.h

@@ -13,6 +13,7 @@
 #ifndef SWIFT_AST_CAPTURE_INFO_H
 #define SWIFT_AST_CAPTURE_INFO_H
 
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/Basic/OptionSet.h"
 #include "swift/Basic/SourceLoc.h"
@@ -219,7 +220,7 @@ class CaptureInfo {
     return StorageAndFlags.getPointer()->getOpaqueValue();
   }
 
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
   void print(raw_ostream &OS) const;
 };
 

include/swift/AST/ConcreteDeclRef.h

@@ -17,6 +17,7 @@
 #ifndef SWIFT_AST_CONCRETEDECLREF_H
 #define SWIFT_AST_CONCRETEDECLREF_H
 
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/AST/SubstitutionMap.h"
 #include "swift/AST/TypeAlignments.h"
@@ -81,8 +82,8 @@ class ConcreteDeclRef {
   }
 
   /// Dump a debug representation of this reference.
-  void dump(raw_ostream &os);
-  void dump() LLVM_ATTRIBUTE_USED;
+  void dump(raw_ostream &os) const;
+  SWIFT_DEBUG_DUMP;
 };
 
 } // end namespace swift

include/swift/AST/Decl.h

@@ -35,6 +35,7 @@
 #include "swift/AST/Witness.h"
 #include "swift/Basic/ArrayRefView.h"
 #include "swift/Basic/Compiler.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/InlineBitfield.h"
 #include "swift/Basic/NullablePtr.h"
 #include "swift/Basic/OptionalEnum.h"
@@ -776,12 +777,8 @@ class alignas(1 << DeclAlignInBits) Decl {
 
   SourceLoc TrailingSemiLoc;
 
-  LLVM_ATTRIBUTE_DEPRECATED(
-      void dump() const LLVM_ATTRIBUTE_USED,
-      "only for use within the debugger");
-  LLVM_ATTRIBUTE_DEPRECATED(
-      void dump(const char *filename) const LLVM_ATTRIBUTE_USED,
-      "only for use within the debugger");
+  SWIFT_DEBUG_DUMP;
+  SWIFT_DEBUG_DUMPER(dump(const char *filename));
   void dump(raw_ostream &OS, unsigned Indent = 0) const;
 
   /// Pretty-print the given declaration.
@@ -1202,9 +1199,7 @@ class RequirementRepr {
     return repr->SecondType.getTypeRepr();
   }
 
-  LLVM_ATTRIBUTE_DEPRECATED(
-      void dump() const LLVM_ATTRIBUTE_USED,
-      "only for use within the debugger");
+  SWIFT_DEBUG_DUMP;
   void print(raw_ostream &OS) const;
   void print(ASTPrinter &Printer) const;
 };
@@ -1374,7 +1369,7 @@ class GenericParamList final :
   GenericParamList *clone(DeclContext *dc) const;
 
   void print(raw_ostream &OS) const;
-  void dump();
+  SWIFT_DEBUG_DUMP;
 };
 
 /// A trailing where clause.
@@ -2714,7 +2709,7 @@ class ValueDecl : public Decl {
   void dumpRef(raw_ostream &os) const;
 
   /// Dump a reference to the given declaration.
-  void dumpRef() const;
+  SWIFT_DEBUG_DUMPER(dumpRef());
 
   /// Returns true if the declaration is a static member of a type.
   ///

include/swift/AST/DeclContext.h

@@ -23,6 +23,7 @@
 #include "swift/AST/LookupKinds.h"
 #include "swift/AST/ResilienceExpansion.h"
 #include "swift/AST/TypeAlignments.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/Basic/STLExtras.h"
 #include "swift/Basic/SourceLoc.h"
@@ -597,7 +598,7 @@ class alignas(1 << DeclContextAlignInBits) DeclContext {
   /// \returns true if traversal was aborted, false otherwise.
   bool walkContext(ASTWalker &Walker);
 
-  void dumpContext() const;
+  SWIFT_DEBUG_DUMPER(dumpContext());
   unsigned printContext(llvm::raw_ostream &OS, unsigned indent = 0,
                         bool onlyAPartialLine = false) const;
 

include/swift/AST/Evaluator.h

@@ -20,6 +20,7 @@
 
 #include "swift/AST/AnyRequest.h"
 #include "swift/Basic/AnyValue.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/Defer.h"
 #include "swift/Basic/Statistic.h"
 #include "llvm/ADT/DenseMap.h"
@@ -452,17 +453,13 @@ class Evaluator {
 
   /// Dump the dependencies of the given request to the debugging stream
   /// as a tree.
-  LLVM_ATTRIBUTE_DEPRECATED(
-    void dumpDependencies(const AnyRequest &request) const LLVM_ATTRIBUTE_USED,
-    "Only meant for use in the debugger");
+  SWIFT_DEBUG_DUMPER(dumpDependencies(const AnyRequest &request));
 
   /// Print all dependencies known to the evaluator as a single Graphviz
   /// directed graph.
   void printDependenciesGraphviz(llvm::raw_ostream &out) const;
 
-  LLVM_ATTRIBUTE_DEPRECATED(
-    void dumpDependenciesGraphviz() const LLVM_ATTRIBUTE_USED,
-    "Only meant for use in the debugger");
+  SWIFT_DEBUG_DUMPER(dumpDependenciesGraphviz());
 };
 
 template <typename Request>

include/swift/AST/ExperimentalDependencies.h

@@ -13,6 +13,7 @@
 #ifndef SWIFT_AST_EXPERIMENTAL_DEPENDENCIES_H
 #define SWIFT_AST_EXPERIMENTAL_DEPENDENCIES_H
 
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/LLVM.h"
 #include "swift/Basic/Range.h"
 #include "llvm/ADT/Hashing.h"
@@ -498,7 +499,8 @@ class DependencyKey {
 
   std::string humanReadableName() const;
 
-  void dump() const { llvm::errs() << asString() << "\n"; }
+  void dump(llvm::raw_ostream &os) const { os << asString() << "\n"; }
+  SWIFT_DEBUG_DUMP { dump(llvm::errs()); }
 
   /// For debugging, needed for \ref TwoStageMap::verify
   std::string asString() const;
@@ -609,7 +611,8 @@ class DepGraphNode {
   /// needs to set the fingerprint *after* the node has been created.
   void setFingerprint(Optional<std::string> fp) { fingerprint = fp; }
 
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
+  void dump(llvm::raw_ostream &os) const;
 
   std::string humanReadableName(StringRef where) const;
 
@@ -685,7 +688,6 @@ class SourceFileDepGraphNode : public DepGraphNode {
     if (n != getSequenceNumber())
       defsIDependUpon.insert(n);
   }
-  void dump() const { DepGraphNode::dump(); }
 
   std::string humanReadableName() const {
     return DepGraphNode::humanReadableName("here");

include/swift/AST/Expr.h

@@ -27,6 +27,7 @@
 #include "swift/AST/TypeAlignments.h"
 #include "swift/AST/TypeLoc.h"
 #include "swift/AST/Availability.h"
+#include "swift/Basic/Debug.h"
 #include "swift/Basic/InlineBitfield.h"
 #include "llvm/Support/TrailingObjects.h"
 #include <utility>
@@ -540,9 +541,7 @@ class alignas(8) Expr {
   /// leaf node, etc.
   llvm::DenseMap<Expr *, unsigned> getPreorderIndexMap();
 
-  LLVM_ATTRIBUTE_DEPRECATED(
-      void dump() const LLVM_ATTRIBUTE_USED,
-      "only for use within the debugger");
+  SWIFT_DEBUG_DUMP;
   void dump(raw_ostream &OS, unsigned Indent = 0) const;
   void dump(raw_ostream &OS, llvm::function_ref<Type(const Expr *)> getType,
             llvm::function_ref<Type(const TypeLoc &)> getTypeOfTypeLoc,

include/swift/AST/GenericEnvironment.h

@@ -21,6 +21,7 @@
 #include "swift/AST/GenericSignature.h"
 #include "swift/AST/GenericParamKey.h"
 #include "swift/Basic/Compiler.h"
+#include "swift/Basic/Debug.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/TrailingObjects.h"
@@ -160,7 +161,7 @@ class alignas(1 << DeclAlignInBits) GenericEnvironment final
 
   void dump(raw_ostream &os) const;
 
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
 };
 
 } // end namespace swift

include/swift/AST/GenericSignature.h

@@ -21,6 +21,7 @@
 #include "swift/AST/Requirement.h"
 #include "swift/AST/Type.h"
 #include "swift/Basic/AnyValue.h"
+#include "swift/Basic/Debug.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/FoldingSet.h"
 #include "llvm/ADT/SmallVector.h"
@@ -89,7 +90,7 @@ class ConformanceAccessPath {
 
   void print(raw_ostream &OS) const;
 
-  LLVM_ATTRIBUTE_DEPRECATED(void dump() const, "only for use in a debugger");
+  SWIFT_DEBUG_DUMP;
 };
 
 class GenericSignatureImpl;
@@ -136,7 +137,7 @@ class GenericSignature {
 
   void print(raw_ostream &OS, PrintOptions Options = PrintOptions()) const;
   void print(ASTPrinter &Printer, PrintOptions Opts = PrintOptions()) const;
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
   std::string getAsString() const;
 
   // Support for FoldingSet.
@@ -408,7 +409,7 @@ class alignas(1 << TypeAlignInBits) GenericSignatureImpl final
 
   void print(raw_ostream &OS, PrintOptions Options = PrintOptions()) const;
   void print(ASTPrinter &Printer, PrintOptions Opts = PrintOptions()) const;
-  void dump() const;
+  SWIFT_DEBUG_DUMP;
   std::string getAsString() const;
 };