Add `#pragma clang deprecated`, used to deprecate macros

[erik.pilkington]

Summary

This patch adds support for #pragma clang deprecated, which emits a deprecated warning whenever it is encountered. This is intended to be used to deprecate macros, but it seems like it could be useful for deprecating include files as well (rather than #warning). This is similar to #pragma GCC warning, but that can't emit a diagnostic under -Wdeprecated, so these warnings wouldn't be controlled by traditional deprecation disabling methods. (-Wno-deprecated, #pragma clang diagnostic ignored).

rdar://problem/50356322 clang should provide a pragma to allow us to deprecate macros

[erik.pilkington]

Marking as "planned changes" to get this out of review queues. Aaron Ballman wants to add "macro attributes", which would be a better way of solving this problem, and is going to ask the C and C++ committees if there is an appetite for such an idea. This is blocked on getting that answer.

[erik.pilkington]

@aaron.ballman: Did you happen to get any feedback on macro attributes? There are a growing number of macros that we'd like to be able to deprecate, and having a workable solution would be useful for us.

[aaron.ballman]

In D67935#2251145, @erik.pilkington wrote:

@aaron.ballman: Did you happen to get any feedback on macro attributes? There are a growing number of macros that we'd like to be able to deprecate, and having a workable solution would be useful for us.

Thank you for bringing this back up! I've worked on a patch to add preprocessor attributes to clang but have set it aside because it feels like it may be an awkward fit because of attribute arguments -- for instance, the preprocessor has no type system or AST, so we track values for things with APValue objects and there is no string APValue type, so it would be a fair amount of work to support # [[deprecated("don't use baz")]] define BAZ, let alone the more esoteric situations for arbitrary attributes. Another issue is that the preprocessor is sometimes shared between C/C++ frontends and, say, a FORTRAN frontend, which could suddenly introduce a new feature into a FORTRAN compiler without extra work.

Based on all of that, I think we should go with your approach of using a #pragma as it does solve a problem and isn't quite as novel. However, I am wondering about the design a bit -- why are you using a string literal to supply the macro name? It's my understanding that all preprocessing directives are executed at the same phase of translation (so you don't have to worry about #define changing the behavior of #pragma or _Pragma), so I would have expected a design more like:

#define FOOBAR(x) whatever(x)
#pragma clang deprecated(FOOBAR, "don't use FOOBAR, it will do bad things")

This feels like a more approachable way to expose the feature, to me, but I wonder if I'm missing something.

Other feedback is: should we diagnose if the pp-token for the macro identifier doesn't actually match the name of a macro? Or are we allowing constructs like:

#pragma clang deprecated(FOOBAR, "don't use FOOBAR, twelve is a terrible number")
#define FOOBAR 12

clang/lib/Lex/Pragma.cpp

1544

Do we want to allow arbitrary string literals, or only narrow character string literals? e.g., should we disallow something like: #pragma clang deprecated(L"oops", U"hahahaha") ?

clang/test/Lexer/pragma-deprecated.c

17–20

What is the utility of unconditionally emitting a diagnostic like this? We've already got #warning.

clang/docs/LanguageExtensions.rst

     // Previous line preprocesses to:
     // __builtin___strlcpy_chk(buffer, "some string", strlen("some string"), __builtin_object_size(buffer, 0))
   }
 
 Since the size of ``buffer`` can't be known at compile time, Clang will fold
 ``__builtin_object_size(buffer, 0)`` into ``-1``. However, if this was written
 as ``__builtin_dynamic_object_size(buffer, 0)``, Clang will fold it into
 ``size``, providing some extra runtime safety.
+
+Deprecating Macros and Files
+============================
+
+Clang supports the pragma ``#pragma clang deprecated``, which is useful for
+deprecating macros or files. For instance:
+
+.. code-block:: c
+
+   #define STR(x) #x
+   #define DEPRECATED_MACRO(entity, message) \
+     _Pragma(STR(clang deprecated(entity, message)))
+
+   #define SWAP(x, y) \
+     DEPRECATED_MACRO("SWAP", "use std::swap instead") \
+     ((x) ^= (y), (y) ^= (x), (x) ^= (y))
+
+   void f(int a, int b) {
+     SWAP(a, b); // warning: SWAP is deprecated: use std::swap instead
+   }
+
+``#pragma clang deprecated`` should be preferred for this purpose over
+``#pragma GCC warning`` because the warning can be controlled with
+``-Wdeprecated``.

clang/include/clang/Basic/DiagnosticGroups.td

 def FinalDtorNonFinalClass : DiagGroup<"final-dtor-non-final-class">;
 
 def CXX11CompatDeprecatedWritableStr :
   DiagGroup<"c++11-compat-deprecated-writable-strings">;
 
 def DeprecatedAttributes : DiagGroup<"deprecated-attributes">;
 def DeprecatedCommaSubscript : DiagGroup<"deprecated-comma-subscript">;
 def DeprecatedDeclarations : DiagGroup<"deprecated-declarations">;
+def DeprecatedPragma : DiagGroup<"deprecated-pragma">;
 def UnavailableDeclarations : DiagGroup<"unavailable-declarations">;
 def UnguardedAvailabilityNew : DiagGroup<"unguarded-availability-new">;
 def UnguardedAvailability : DiagGroup<"unguarded-availability",
                                       [UnguardedAvailabilityNew]>;
 // partial-availability is an alias of unguarded-availability.
 def : DiagGroup<"partial-availability", [UnguardedAvailability]>;
 def DeprecatedDynamicExceptionSpec
     : DiagGroup<"deprecated-dynamic-exception-spec">;
 def DeprecatedImplementations :DiagGroup<"deprecated-implementations">;
 def DeprecatedIncrementBool : DiagGroup<"deprecated-increment-bool">;
 def DeprecatedRegister : DiagGroup<"deprecated-register">;
 def DeprecatedThisCapture : DiagGroup<"deprecated-this-capture">;
 def DeprecatedWritableStr : DiagGroup<"deprecated-writable-strings",
                                       [CXX11CompatDeprecatedWritableStr]>;
 // FIXME: Why is DeprecatedImplementations not in this group?
 def Deprecated : DiagGroup<"deprecated", [DeprecatedAttributes,
                                           DeprecatedCommaSubscript,
                                           DeprecatedDeclarations,
+                                          DeprecatedPragma,
                                           DeprecatedDynamicExceptionSpec,
                                           DeprecatedIncrementBool,
                                           DeprecatedRegister,
                                           DeprecatedThisCapture,
                                           DeprecatedWritableStr]>,
                  DiagCategory<"Deprecations">;
 
 def CXX2aDesignator : DiagGroup<"c++2a-designator">;

clang/include/clang/Basic/DiagnosticLexKinds.td

   InGroup<UnknownPragmas>;
 def warn_pragma_warning_push_level :
   ExtWarn<"#pragma warning(push, level) requires a level between 0 and 4">,
   InGroup<UnknownPragmas>;
 def warn_pragma_warning_expected_number :
   ExtWarn<"#pragma warning expected a warning number">,
   InGroup<UnknownPragmas>;
 
+// - #pragma clang deprecated
+def warn_pragma_deprecated :
+  Warning<"'%0' is deprecated">, InGroup<DeprecatedPragma>;
+def warn_pragma_deprecated_msg :
+  Warning<"'%0' is deprecated: %1">, InGroup<DeprecatedPragma>;
+
 // - #pragma execution_character_set(...)
 def warn_pragma_exec_charset_expected :
   ExtWarn<"#pragma execution_character_set expected '%0'">,
   InGroup<UnknownPragmas>;
 def warn_pragma_exec_charset_spec_invalid :
   ExtWarn<"#pragma execution_character_set expected 'push' or 'pop'">,
   InGroup<UnknownPragmas>;
 def warn_pragma_exec_charset_push_invalid :

clang/lib/Lex/Pragma.cpp

                           : diag::warn_pragma_message) << MessageString;
 
     // If the pragma is lexically sound, notify any interested PPCallbacks.
     if (PPCallbacks *Callbacks = PP.getPPCallbacks())
       Callbacks->PragmaMessage(MessageLoc, Namespace, Kind, MessageString);
   }
 };
 
+/// Handle '#pragma clang deprecated'. The syntax is:
+///
+/// \code
+///   #pragma clang deprecated("entity", "message")
+/// \endcode
+///
+/// The message is optional. This is used to deprecate macros (via _Pragma), or
+/// files.
+struct PragmaDeprecatedHandler : public PragmaHandler {
+  PragmaDeprecatedHandler() : PragmaHandler("deprecated") {}
+
+  void HandlePragma(Preprocessor &PP, PragmaIntroducer Introducer,
+                    Token &NameTok) override {
+    SourceLocation Loc = NameTok.getLocation();
+    std::string EntityString, MessageString;
+    Token Tok;
+
+    PP.Lex(Tok);
+    if (Tok.isNot(tok::l_paren)) {
+      PP.Diag(Loc, diag::err_expected) << tok::l_paren;
+      return;
+    }
+
+    PP.Lex(Tok);
+    if (!PP.FinishLexStringLiteral(Tok, EntityString,
+                                   "#pragma clang deprecated",
+                                   /*AllowMacroExpansion=*/true))
+      return;
+
+    if (Tok.is(tok::comma)) {
+      PP.Lex(Tok);
+      if (!PP.FinishLexStringLiteral(Tok, MessageString,
+                                     "#pragma clang deprecated",
+                                     /*AllowMacroExpansion=*/true))
+        return;
+    }
+
+    if (Tok.isNot(tok::r_paren)) {
+      PP.Diag(Loc, diag::err_expected) << tok::r_paren;
+      return;
+    }
+
+    PP.Lex(Tok);
+    if (Tok.isNot(tok::eod))
+      PP.Diag(Loc, diag::ext_pp_extra_tokens_at_eol) << "pragma";
+
+    unsigned DiagID = MessageString.empty() ? diag::warn_pragma_deprecated
+                                            : diag::warn_pragma_deprecated_msg;
+    DiagnosticBuilder Builder = PP.Diag(Loc, DiagID)
+                                << EntityString << MessageString;
+  }
+};
+
 /// Handle the clang \#pragma module import extension. The syntax is:
 /// \code
 ///   #pragma clang module import some.module.name
 /// \endcode
 struct PragmaModuleImportHandler : public PragmaHandler {
   PragmaModuleImportHandler() : PragmaHandler("import") {}
 
   void HandlePragma(Preprocessor &PP, PragmaIntroducer Introducer,

   // #pragma clang ...
   AddPragmaHandler("clang", new PragmaPoisonHandler());
   AddPragmaHandler("clang", new PragmaSystemHeaderHandler());
   AddPragmaHandler("clang", new PragmaDebugHandler());
   AddPragmaHandler("clang", new PragmaDependencyHandler());
   AddPragmaHandler("clang", new PragmaDiagnosticHandler("clang"));
   AddPragmaHandler("clang", new PragmaARCCFCodeAuditedHandler());
   AddPragmaHandler("clang", new PragmaAssumeNonNullHandler());
+  AddPragmaHandler("clang", new PragmaDeprecatedHandler);
 
   // #pragma clang module ...
   auto *ModuleHandler = new PragmaNamespace("module");
   AddPragmaHandler("clang", ModuleHandler);
   ModuleHandler->AddPragma(new PragmaModuleImportHandler());
   ModuleHandler->AddPragma(new PragmaModuleBeginHandler());
   ModuleHandler->AddPragma(new PragmaModuleEndHandler());
   ModuleHandler->AddPragma(new PragmaModuleBuildHandler());

clang/test/Lexer/pragma-deprecated.c

+// RUN: %clang_cc1 -verify -Wdeprecated-pragma %s
+
+#define STR(x) #x
+#define DEPRECATED_MACRO(entity, message) \
+  _Pragma(STR(clang deprecated(entity, message)))
+
+#define FOO DEPRECATED_MACRO("foo", "use bar") 43
+
+__attribute__((deprecated))
+int f();
+
+int main() {
+  return FOO; // expected-warning{{'foo' is deprecated: use bar}}
+}
+
+// expected-warning@+1{{'"flerp.h"' is deprecated: use "flarp.h" instead}}
+#pragma clang deprecated("\"flerp.h\"", "use \"flarp.h\" instead")
+
+// expected-warning@+1{{'flerp' is deprecated}}
+#pragma clang deprecated("flerp")
+
+// expected-error@+1 {{expected '('}}
+#pragma clang deprecated
+// expected-error@+1 {{expected string literal in #pragma clang deprecated}}
+#pragma clang deprecated(43)
+// expected-error@+1 {{expected string literal in #pragma clang deprecated}}
+#pragma clang deprecated ("foo", 33)
+// expected-error@+1 {{expected ')'}}
+#pragma clang deprecated ("foo", "bar"
+// expected-warning@+2 {{extra tokens at end of #pragma directive}}
+// expected-warning@+1 {{'foo' is deprecated: bar}}
+#pragma clang deprecated ("foo", "bar") baz