[llvm-c] Add header deprecations

[nikic]

Summary

This adds support for header deprecation using LLVM_ATTRIBUTE_C_DEPRECATED (note that we can't use LLVM_ATTRIBUTE_DEPRECATED, which is C++ specific). This will not help people using the FFI interface, but may help people using the C headers.

While migrating the test code away from deprecated APIs I had to add a LLVMGetGEPSourceElementType() function, as the necessary functionality didn't seem to be present yet.

[aeubanks]

it'd be nice to split out the API changes and the deprecation macro addition, but not a huge deal

llvm/include/llvm-c/Core.h

3685–3686

could move these comments into the deprecation message

[dblaikie]

In D114936#3167416, @aeubanks wrote:

it'd be nice to split out the API changes and the deprecation macro addition, but not a huge deal

Yep, +1 to that - submit the API changes/fixes first, then the deprecations.

[uabelho]

Hi,

I think more fixes are needed. With this commit I see:

../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:206:5: error: 'LLVMBuildCall' is deprecated: Use LLVMBuildCall2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
    LLVMBuildCall(builder, stackmap, stackmapArgs, 3, "");
    ^
../include/llvm-c/Core.h:3985:1: note: 'LLVMBuildCall' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:233:31: error: 'LLVMBuildLoad' is deprecated: Use LLVMBuildLoad2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
        LLVMValueRef IntVal = LLVMBuildLoad(Builder, GlobalVar, "intVal");
                              ^
../include/llvm-c/Core.h:3885:1: note: 'LLVMBuildLoad' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:492:25: error: 'LLVMBuildCall' is deprecated: Use LLVMBuildCall2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
  LLVMValueRef RetVal = LLVMBuildCall(Builder, MappedFn, nullptr, 0, "");
                        ^
../include/llvm-c/Core.h:3985:1: note: 'LLVMBuildCall' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
3 errors generated.

[nikic]

In D114936#3173327, @uabelho wrote:

Hi,

I think more fixes are needed. With this commit I see:

../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:206:5: error: 'LLVMBuildCall' is deprecated: Use LLVMBuildCall2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
    LLVMBuildCall(builder, stackmap, stackmapArgs, 3, "");
    ^
../include/llvm-c/Core.h:3985:1: note: 'LLVMBuildCall' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:233:31: error: 'LLVMBuildLoad' is deprecated: Use LLVMBuildLoad2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
        LLVMValueRef IntVal = LLVMBuildLoad(Builder, GlobalVar, "intVal");
                              ^
../include/llvm-c/Core.h:3885:1: note: 'LLVMBuildLoad' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
../unittests/ExecutionEngine/MCJIT/MCJITCAPITest.cpp:492:25: error: 'LLVMBuildCall' is deprecated: Use LLVMBuildCall2 instead to support opaque pointers [-Werror,-Wdeprecated-declarations]
  LLVMValueRef RetVal = LLVMBuildCall(Builder, MappedFn, nullptr, 0, "");
                        ^
../include/llvm-c/Core.h:3985:1: note: 'LLVMBuildCall' has been explicitly marked deprecated here
LLVM_ATTRIBUTE_C_DEPRECATED(
^
../include/llvm-c/Deprecated.h:26:23: note: expanded from macro 'LLVM_ATTRIBUTE_C_DEPRECATED'
  decl __attribute__((deprecated(message)))
                      ^
3 errors generated.

Oops, sorry about that, I missed building the unit tests once again. Should be fixed by https://github.com/llvm/llvm-project/commit/24a72dc070b36d9e62d6b84abe5f1912c5a49581.

[aaronpuchert]

Nice to see that we have this now! (There was an earlier attempt in D18964 that somehow didn't make it.)

llvm/include/llvm-c/Deprecated.h

26–29

Can't we always place the attribute in front of the declaration, and then remove the need to pass decl into the macro? Then we could write

LLVM_ATTRIBUTE_C_DEPRECATED("Use LLVMBar instead")
void LLVMFoo(void);

llvm/include/llvm-c/Core.h

 |* This header declares the C interface to libLLVMCore.a, which implements    *|
 |* the LLVM intermediate representation.                                      *|
 |*                                                                            *|
 \*===----------------------------------------------------------------------===*/
 
 #ifndef LLVM_C_CORE_H
 #define LLVM_C_CORE_H
 
+#include "llvm-c/Deprecated.h"
 #include "llvm-c/ErrorHandling.h"
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
  * @defgroup LLVMC LLVM-C: C interface to LLVM

  *
  * This group contains function that operate on global alias values.
  *
  * @see llvm::GlobalAlias
  *
  * @{
  */
 
-/** Deprecated: Use LLVMAddAlias2 instead. */
-LLVMValueRef LLVMAddAlias(LLVMModuleRef M, LLVMTypeRef Ty, LLVMValueRef Aliasee,
-                          const char *Name);
+LLVM_ATTRIBUTE_C_DEPRECATED(
+    LLVMValueRef LLVMAddAlias(LLVMModuleRef M, LLVMTypeRef Ty,
+                              LLVMValueRef Aliasee, const char *Name),
+    "Use LLVMAddAlias2 instead to support opaque pointers");
 
 /**
  * Add a GlobalAlias with the given value type, address space and aliasee.
  *
  * @see llvm::GlobalAlias::create()
  */
 LLVMValueRef LLVMAddAlias2(LLVMModuleRef M, LLVMTypeRef ValueTy,
                            unsigned AddrSpace, LLVMValueRef Aliasee,

 LLVMValueRef LLVMBuildAggregateRet(LLVMBuilderRef, LLVMValueRef *RetVals,
                                    unsigned N);
 LLVMValueRef LLVMBuildBr(LLVMBuilderRef, LLVMBasicBlockRef Dest);
 LLVMValueRef LLVMBuildCondBr(LLVMBuilderRef, LLVMValueRef If,
                              LLVMBasicBlockRef Then, LLVMBasicBlockRef Else);
 LLVMValueRef LLVMBuildSwitch(LLVMBuilderRef, LLVMValueRef V,
                              LLVMBasicBlockRef Else, unsigned NumCases);
 LLVMValueRef LLVMBuildIndirectBr(LLVMBuilderRef B, LLVMValueRef Addr,
                                  unsigned NumDests);
-// LLVMBuildInvoke is deprecated in favor of LLVMBuildInvoke2, in preparation
-// for opaque pointer types.
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildInvoke(LLVMBuilderRef, LLVMValueRef Fn,
                                  LLVMValueRef *Args, unsigned NumArgs,
-                             LLVMBasicBlockRef Then, LLVMBasicBlockRef Catch,
-                             const char *Name);
+                                 LLVMBasicBlockRef Then,
+                                 LLVMBasicBlockRef Catch, const char *Name),
+    "Use LLVMBuildInvoke2 instead to support opaque pointers");
 LLVMValueRef LLVMBuildInvoke2(LLVMBuilderRef, LLVMTypeRef Ty, LLVMValueRef Fn,
                               LLVMValueRef *Args, unsigned NumArgs,
                               LLVMBasicBlockRef Then, LLVMBasicBlockRef Catch,
                               const char *Name);
 LLVMValueRef LLVMBuildUnreachable(LLVMBuilderRef);
 
 /* Exception Handling */
 LLVMValueRef LLVMBuildResume(LLVMBuilderRef B, LLVMValueRef Exn);
LLVMValueRef LLVMBuildMemMove(LLVMBuilderRef B,
                               LLVMValueRef Dst, unsigned DstAlign,
                               LLVMValueRef Src, unsigned SrcAlign,
                               LLVMValueRef Size);
 
 LLVMValueRef LLVMBuildAlloca(LLVMBuilderRef, LLVMTypeRef Ty, const char *Name);
 LLVMValueRef LLVMBuildArrayAlloca(LLVMBuilderRef, LLVMTypeRef Ty,
                                   LLVMValueRef Val, const char *Name);
 LLVMValueRef LLVMBuildFree(LLVMBuilderRef, LLVMValueRef PointerVal);
-// LLVMBuildLoad is deprecated in favor of LLVMBuildLoad2, in preparation for
-// opaque pointer types.
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildLoad(LLVMBuilderRef, LLVMValueRef PointerVal,
-                           const char *Name);
+                               const char *Name),
+    "Use LLVMBuildLoad2 instead to support opaque pointers");
 LLVMValueRef LLVMBuildLoad2(LLVMBuilderRef, LLVMTypeRef Ty,
                             LLVMValueRef PointerVal, const char *Name);
 LLVMValueRef LLVMBuildStore(LLVMBuilderRef, LLVMValueRef Val, LLVMValueRef Ptr);
-// LLVMBuildGEP, LLVMBuildInBoundsGEP, and LLVMBuildStructGEP are deprecated in
-// favor of LLVMBuild*GEP2, in preparation for opaque pointer types.
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildGEP(LLVMBuilderRef B, LLVMValueRef Pointer,
                               LLVMValueRef *Indices, unsigned NumIndices,
-                          const char *Name);
+                              const char *Name),
+    "Use LLVMBuildGEP2 instead to support opaque pointers");
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildInBoundsGEP(LLVMBuilderRef B, LLVMValueRef Pointer,
-                                  LLVMValueRef *Indices, unsigned NumIndices,
-                                  const char *Name);
+                                      LLVMValueRef *Indices,
+                                      unsigned NumIndices, const char *Name),
+    "Use LLVMBuildInBoundsGEP2 instead to support opaque pointers");
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildStructGEP(LLVMBuilderRef B, LLVMValueRef Pointer,
-                                unsigned Idx, const char *Name);
+                                    unsigned Idx, const char *Name),
+    "Use LLVMBuildStructGEP2 instead to support opaque pointers");
 LLVMValueRef LLVMBuildGEP2(LLVMBuilderRef B, LLVMTypeRef Ty,
                            LLVMValueRef Pointer, LLVMValueRef *Indices,
                            unsigned NumIndices, const char *Name);
 LLVMValueRef LLVMBuildInBoundsGEP2(LLVMBuilderRef B, LLVMTypeRef Ty,
                                    LLVMValueRef Pointer, LLVMValueRef *Indices,
                                    unsigned NumIndices, const char *Name);
 LLVMValueRef LLVMBuildStructGEP2(LLVMBuilderRef B, LLVMTypeRef Ty,
                                  LLVMValueRef Pointer, unsigned Idx,
LLVMValueRef LLVMBuildICmp(LLVMBuilderRef, LLVMIntPredicate Op,
                            LLVMValueRef LHS, LLVMValueRef RHS,
                            const char *Name);
 LLVMValueRef LLVMBuildFCmp(LLVMBuilderRef, LLVMRealPredicate Op,
                            LLVMValueRef LHS, LLVMValueRef RHS,
                            const char *Name);
 
 /* Miscellaneous instructions */
 LLVMValueRef LLVMBuildPhi(LLVMBuilderRef, LLVMTypeRef Ty, const char *Name);
-// LLVMBuildCall is deprecated in favor of LLVMBuildCall2, in preparation for
-// opaque pointer types.
+LLVM_ATTRIBUTE_C_DEPRECATED(
     LLVMValueRef LLVMBuildCall(LLVMBuilderRef, LLVMValueRef Fn,
                                LLVMValueRef *Args, unsigned NumArgs,
-                           const char *Name);
+                               const char *Name),
+    "Use LLVMBuildCall2 instead to support opaque pointers");
 LLVMValueRef LLVMBuildCall2(LLVMBuilderRef, LLVMTypeRef, LLVMValueRef Fn,
                             LLVMValueRef *Args, unsigned NumArgs,
                             const char *Name);
 LLVMValueRef LLVMBuildSelect(LLVMBuilderRef, LLVMValueRef If,
                              LLVMValueRef Then, LLVMValueRef Else,
                              const char *Name);
 LLVMValueRef LLVMBuildVAArg(LLVMBuilderRef, LLVMValueRef List, LLVMTypeRef Ty,
                             const char *Name);

llvm/include/llvm-c/Deprecated.h

+/*===-- llvm-c/Deprecated.h - Deprecation macro -------------------*- C -*-===*\
+|*                                                                            *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
+|*                                                                            *|
+|*===----------------------------------------------------------------------===*|
+|*                                                                            *|
+|* This header declares LLVM_ATTRIBUTE_C_DEPRECATED() macro, which can be     *|
+|* used to deprecate functions in the C interface.                            *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef LLVM_C_DEPRECATED_H
+#define LLVM_C_DEPRECATED_H
+
+#ifndef __has_feature
+# define __has_feature(x) 0
+#endif
+
+// This is a variant of LLVM_ATTRIBUTE_DEPRECATED() that is compatible with
+// C compilers.
+#if __has_feature(attribute_deprecated_with_message)
+# define LLVM_ATTRIBUTE_C_DEPRECATED(decl, message) \
+  decl __attribute__((deprecated(message)))
+#elif defined(__GNUC__)
+# define LLVM_ATTRIBUTE_C_DEPRECATED(decl, message) \
+  decl __attribute__((deprecated))
+#elif defined(_MSC_VER)
+# define LLVM_ATTRIBUTE_C_DEPRECATED(decl, message) \
+  __declspec(deprecated(message)) decl
+#else
+# define LLVM_ATTRIBUTE_C_DEPRECATED(decl, message) \
+  decl
+#endif
+
+#endif /* LLVM_C_DEPRECATED_H */