[lldb] Introduce a macro to mark methods as unsupported with no replacement

[bulbazord]

Summary

We already have LLDB_DEPRECATED which is used to mark methods as
deprecated with a message and an alternative to use instead. This is
expresses an intent of "We recognize this functionality is useful but
there are some pitfalls with the interface we have exposed."

In other cases, there are no "alternative" methods to use and the code should be
refactored to avoid using a method entirely. For example,
SBValue::Cast should be avoided in favor of using the expression
evaluator to perform a cast. There isn't a mechanical solution, the
recommendation is to instead refactor your code. This commit introduces a
different macro to distinguish this case from the first.

[mib]

lldb/include/lldb/lldb-defines.h

137–143

If we don't have a fix, we should just use the regular [[deprecated(message)] synthax.

[bulbazord]

lldb/include/lldb/lldb-defines.h

137–143

Ah, good point. Will update.

[JDevlieghere]

As discussed offline, I think it's impossible to enforce the semantic difference between the two and we'll inevitable end up with the LLDB_UNSUPPORTED used where LLDB_DEPRECATED should be used but someone didn't know, or worse someone decides to add a third macro to mean something slightly different. My suggestion was to have the two macros be named the same modulo a suffix to indicate whether there's a message or not (for example LLDB_DEPRECATED_FIX or LLDB_DEPRECATED_FIXIT and LLDB_DEPRECATED if there's not).

[bulbazord]

Implement changes after discussing offline with Jonas and Ismail

[JDevlieghere]

LGTM

lldb/include/lldb/API/SBCommandReturnObject.h

public:
 
   bool IsValid() const;
 
   const char *GetOutput();
 
   const char *GetError();
 
 #ifndef SWIG
-  LLDB_DEPRECATED("Use PutOutput(SBFile) or PutOutput(FileSP)",
+  LLDB_DEPRECATED_FIXME("Use PutOutput(SBFile) or PutOutput(FileSP)",
                         "PutOutput(SBFile)")
   size_t PutOutput(FILE *fh);
 #endif
 
   size_t PutOutput(SBFile file);
 
   size_t PutOutput(FileSP BORROWED);
 
   size_t GetOutputSize();
 
   size_t GetErrorSize();
 
 #ifndef SWIG
-  LLDB_DEPRECATED("Use PutError(SBFile) or PutError(FileSP)",
+  LLDB_DEPRECATED_FIXME("Use PutError(SBFile) or PutError(FileSP)",
                         "PutError(SBFile)")
   size_t PutError(FILE *fh);
 #endif
 
   size_t PutError(SBFile file);
 
   size_t PutError(FileSP BORROWED);
 
   void Clear();
 
   lldb::ReturnStatus GetStatus();
 
   void SetStatus(lldb::ReturnStatus status);
 
   bool Succeeded();
 
   bool HasResult();
 
   void AppendMessage(const char *message);
 
   void AppendWarning(const char *message);
 
   bool GetDescription(lldb::SBStream &description);
 
 #ifndef SWIG
-  LLDB_DEPRECATED(
+  LLDB_DEPRECATED_FIXME(
       "Use SetImmediateOutputFile(SBFile) or SetImmediateOutputFile(FileSP)",
       "SetImmediateOutputFile(SBFile)")
   void SetImmediateOutputFile(FILE *fh);
 
-  LLDB_DEPRECATED(
+  LLDB_DEPRECATED_FIXME(
       "Use SetImmediateErrorFile(SBFile) or SetImmediateErrorFile(FileSP)",
       "SetImmediateErrorFile(SBFile)")
   void SetImmediateErrorFile(FILE *fh);
 
-  LLDB_DEPRECATED(
+  LLDB_DEPRECATED_FIXME(
       "Use SetImmediateOutputFile(SBFile) or SetImmediateOutputFile(FileSP)",
       "SetImmediateOutputFile(SBFile)")
   void SetImmediateOutputFile(FILE *fh, bool transfer_ownership);
 
-  LLDB_DEPRECATED(
+  LLDB_DEPRECATED_FIXME(
       "Use SetImmediateErrorFile(SBFile) or SetImmediateErrorFile(FileSP)",
       "SetImmediateErrorFile(SBFile)")
   void SetImmediateErrorFile(FILE *fh, bool transfer_ownership);
 #endif
 
   void SetImmediateOutputFile(SBFile file);
 
   void SetImmediateErrorFile(SBFile file);

lldb/include/lldb/API/SBDebugger.h

#endif
   static lldb::SBError InitializeWithErrorHandling();
 
   static void PrintStackTraceOnError();
 
   static void PrintDiagnosticsOnError();
 
   static void Terminate();
 
-  LLDB_DEPRECATED("Use one of the other Create variants", "Create(bool)")
+  LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
   static lldb::SBDebugger Create();
 
   static lldb::SBDebugger Create(bool source_init_files);
 
   static lldb::SBDebugger Create(bool source_init_files,
                                  lldb::LogOutputCallback log_callback,
                                  void *baton);
 
#endif
   
   void RequestInterrupt();
   void CancelInterruptRequest();
   bool InterruptRequested();
 
   lldb::SBListener GetListener();
 
 #ifndef SWIG
-  LLDB_DEPRECATED(
+  LLDB_DEPRECATED_FIXME(
       "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
       "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
       "FileSP, FileSP)",
       "HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, SBFile)")
   void HandleProcessEvent(const lldb::SBProcess &process,
-                          const lldb::SBEvent &event, FILE *out,
-                          FILE *err);
+                          const lldb::SBEvent &event, FILE *out, FILE *err);
 #endif
 
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, SBFile out, SBFile err);
 
 #ifdef SWIG
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED);
#endif
   bool EnableLog(const char *channel, const char **categories);
 
   void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
 
   void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
                           void *baton);
 
 #ifndef SWIG
-  LLDB_DEPRECATED("Use DispatchInput(const void *, size_t)",
+  LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)",
                         "DispatchInput(const void *, size_t)")
   void DispatchInput(void *baton, const void *data, size_t data_len);
 #endif
 
   void DispatchInput(const void *data, size_t data_len);
 
   void DispatchInputInterrupt();
 
   void DispatchInputEndOfFile();

lldb/include/lldb/API/SBDefines.h

 #endif
 #endif
 
 // Don't add the deprecated attribute when generating the bindings or when
 // building for anything older than C++14 which is the first version that
 // supports the attribute.
 #if defined(SWIG) || _cplusplus < 201402L
 #undef LLDB_DEPRECATED
-#define LLDB_DEPRECATED(MSG, FIX)
+#undef LLDB_DEPRECATED_FIXME
+#define LLDB_DEPRECATED(MSG)
+#define LLDB_DEPRECATED_FIXME(MSG, FIX)
 #endif
 
 // Forward Declarations
 namespace lldb {
 
 class LLDB_API SBAddress;
 class LLDB_API SBBlock;
 class LLDB_API SBBreakpoint;

lldb/include/lldb/API/SBFileSpec.h

 namespace lldb {
 
 class LLDB_API SBFileSpec {
 public:
   SBFileSpec();
 
   SBFileSpec(const lldb::SBFileSpec &rhs);
 
-  LLDB_DEPRECATED("Use the other constructor to determine if this the file "
-                  "spec should be resolved",
-                  "SBFileSpec(const char *, bool)")
+  LLDB_DEPRECATED_FIXME(
+      "Use the other constructor to determine if this the file "
   SBFileSpec(const char *path);
 
   SBFileSpec(const char *path, bool resolve);
 
   ~SBFileSpec();
 
   const SBFileSpec &operator=(const lldb::SBFileSpec &rhs);
 

lldb/include/lldb/API/SBProcess.h

public:
   const lldb::SBProcess &operator=(const lldb::SBProcess &rhs);
 
   ~SBProcess();
 
   static const char *GetBroadcasterClassName();
 
   const char *GetPluginName();
 
-  LLDB_DEPRECATED("Use GetPluginName()", "GetPluginName()")
+  LLDB_DEPRECATED_FIXME("Use GetPluginName()", "GetPluginName()")
   const char *GetShortPluginName();
 
   void Clear();
 
   explicit operator bool() const;
 
   bool IsValid() const;
 

lldb/include/lldb/API/SBStructuredData.h

public:
   /// is array.
   lldb::SBStructuredData GetItemAtIndex(size_t idx) const;
 
   /// Return the integer value if this data structure is an integer type.
   uint64_t GetUnsignedIntegerValue(uint64_t fail_value = 0) const;
   /// Return the integer value if this data structure is an integer type.
   int64_t GetSignedIntegerValue(int64_t fail_value = 0) const;
 
-  LLDB_DEPRECATED("Specify if the value is signed or unsigned",
-                  "uint64_t GetUnsignedIntegerValue(uint64_t fail_value = 0)")
+  LLDB_DEPRECATED_FIXME(
+      "Specify if the value is signed or unsigned",
   uint64_t GetIntegerValue(uint64_t fail_value = 0) const;
 
   /// Return the floating point value if this data structure is a floating
   /// type.
   double GetFloatValue(double fail_value = 0.0) const;
 
   /// Return the boolean value if this data structure is a boolean type.
   bool GetBooleanValue(bool fail_value = false) const;

lldb/include/lldb/API/SBTarget.h

#ifndef SWIG
   ///
   /// \param[in] sections_offset
   ///     An offset that will be applied to all section file addresses
   ///     (the virtual addresses found in the object file itself).
   ///
   /// \return
   ///     An error to indicate success, fail, and any reason for
   ///     failure.
-  LLDB_DEPRECATED("Use SetModuleLoadAddress(lldb::SBModule, uint64_t)",
+  LLDB_DEPRECATED_FIXME("Use SetModuleLoadAddress(lldb::SBModule, uint64_t)",
                         "SetModuleLoadAddress(lldb::SBModule, uint64_t)")
   lldb::SBError SetModuleLoadAddress(lldb::SBModule module,
                                      int64_t sections_offset);
 #endif
 
   /// Slide all file addresses for all module sections so that \a module
   /// appears to loaded at these slide addresses.
   ///
   /// When you need all sections within a module to be loaded at a

lldb/include/lldb/API/SBValue.h

public:
   bool IsSynthetic();
 
   bool IsSyntheticChildrenGenerated();
 
   void SetSyntheticChildrenGenerated(bool);
 
   const char *GetLocation();
 
-  LLDB_DEPRECATED("Use the variant that takes an SBError &",
+  LLDB_DEPRECATED_FIXME("Use the variant that takes an SBError &",
                         "SetValueFromCString(const char *, SBError &)")
   bool SetValueFromCString(const char *value_str);
 
   bool SetValueFromCString(const char *value_str, lldb::SBError &error);
 
   lldb::SBTypeFormat GetTypeFormat();
 
   lldb::SBTypeSummary GetTypeSummary();
 
   lldb::SBTypeFilter GetTypeFilter();
 
   lldb::SBTypeSynthetic GetTypeSynthetic();
 
   lldb::SBValue GetChildAtIndex(uint32_t idx);
 
   lldb::SBValue CreateChildAtOffset(const char *name, uint32_t offset,
                                     lldb::SBType type);
 
-  LLDB_DEPRECATED("Use the expression evaluator to perform type casting", "")
+  LLDB_DEPRECATED("Use the expression evaluator to perform type casting")
   lldb::SBValue Cast(lldb::SBType type);
 
   lldb::SBValue CreateValueFromExpression(const char *name,
                                           const char *expression);
 
   lldb::SBValue CreateValueFromExpression(const char *name,
                                           const char *expression,
                                           SBExpressionOptions &options);
public:
   lldb::SBProcess GetProcess();
 
   lldb::SBThread GetThread();
 
   lldb::SBFrame GetFrame();
 
   lldb::SBValue Dereference();
 
-  LLDB_DEPRECATED("Use GetType().IsPointerType() instead", "")
+  LLDB_DEPRECATED("Use GetType().IsPointerType() instead")
   bool TypeIsPointerType();
 
   lldb::SBType GetType();
 
   lldb::SBValue Persist();
 
   bool GetDescription(lldb::SBStream &description);
 

lldb/include/lldb/lldb-defines.h

 
 // ignore GCC function attributes
 #if defined(_MSC_VER) && !defined(__clang__)
 #define __attribute__(X)
 #endif
 
 #define UNUSED_IF_ASSERT_DISABLED(x) ((void)(x))
 
+#define LLDB_DEPRECATED(MSG)                                                   \
+  [[deprecated("This method is no longer supported: " MSG)]]
+
 #if defined(__clang__)
-#define LLDB_DEPRECATED(MSG, FIX) __attribute__((deprecated(MSG, FIX)))
+#define LLDB_DEPRECATED_FIXME(MSG, FIX) __attribute__((deprecated(MSG, FIX)))
 #else
-#define LLDB_DEPRECATED(MSG, FIX) [[deprecated(MSG)]]
+#define LLDB_DEPRECATED_FIXME(MSG, FIX) LLDB_DEPRECATED(MSG)
 #endif
 
 #endif // LLDB_LLDB_DEFINES_H