[llvm] [llvm] add LLVM_FRIEND_ABI macro for friend function decls (PR #136595)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-llvm-support

Author: Andrew Rogers (andrurogerz)

<details>
<summary>Changes</summary>

## Purpose
Introduce a new `LLVM_FRIEND_ABI` macro to `llvm/Support/Compiler.h` for annotating `friend` function declarations for DLL export.

## Overview
1. Add a new `LLVM_FRIEND_ABI` macro, which behaves identically to the existing `LLVM_ABI` macro on Windows and compiles to nothing on other platforms.
2. Update existing documentation to describe proper usage of the `LLVM_FRIEND_ABI` annotation.

## Background
* MSVC issues a warning when it encounters a `friend` function declaration that does not match the DLL import/export annotation of the original function.
* When compiling ELF and Mach-O shared libraries, `friend` function declarations with visibility annotations produce compilation errors (GCC) and warnings (Clang).
* Additional context on the effort to annotate LLVM's public interface is in [this discourse](https://discourse.llvm.org/t/psa-annotating-llvm-public-interface/85307).

---
Full diff: https://github.com/llvm/llvm-project/pull/136595.diff


2 Files Affected:

- (modified) llvm/docs/InterfaceExportAnnotations.rst (+7-6) 
- (modified) llvm/include/llvm/Support/Compiler.h (+10) 


``````````diff
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index eecf6ffe6eaca..715472f644763 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -222,9 +222,10 @@ method in a C++ class, it may be annotated for export.
 
 Friend Functions
 ~~~~~~~~~~~~~~~~
-Friend functions declared in a class, struct or union must be annotated with
-``LLVM_ABI`` if the corresponding function declaration is also annotated. This
-requirement applies even when the class itself is annotated with ``LLVM_ABI``.
+Friend functions declared in a class, struct or union should be annotated with
+``LLVM_FRIEND_ABI`` if the corresponding function declaration is annotated with
+``LLVM_ABI``. This requirement applies even when the class containing the friend
+declaration is annotated with ``LLVM_ABI``.
 
 .. code:: cpp
 
@@ -236,14 +237,14 @@ requirement applies even when the class itself is annotated with ``LLVM_ABI``.
    class ExampleClass {
      // Friend declaration of a function must be annotated the same as the actual
      // function declaration.
-     LLVM_ABI friend int friend_function(ExampleClass &obj);
+     LLVM_FRIEND_ABI friend int friend_function(ExampleClass &obj);
    };
 
 .. note::
 
    Annotating the friend declaration avoids an “inconsistent dll linkage”
-   compiler error when building for Windows. This annotation is harmless but not
-   required when building ELF or Mach-O shared libraries.
+   compiler error when building a DLL for Windows. The ``LLVM_FRIEND_ABI``
+   annotation is a no-op when building ELF or Mach-O shared libraries.
 
 Virtual Table and Type Info
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/llvm/include/llvm/Support/Compiler.h b/llvm/include/llvm/Support/Compiler.h
index d265d864228ca..0f29299a1f0b8 100644
--- a/llvm/include/llvm/Support/Compiler.h
+++ b/llvm/include/llvm/Support/Compiler.h
@@ -167,6 +167,11 @@
 /// for both functions and classes. On windows its turned in to dllimport for
 /// library consumers, for other platforms its a default visibility attribute.
 ///
+/// LLVM_FRIEND_ABI is for annotating friend function declarations when the
+/// target function's original declaration is annotated with LLVM_ABI. This
+/// macro matches the LLVM_ABI macro on Windows, on other platforms it does
+/// nothing.
+///
 /// LLVM_C_ABI is used to annotated functions and data that need to be exported
 /// for the libllvm-c API. This used both for the llvm-c headers and for the
 /// functions declared in the different Target's c++ source files that don't
@@ -183,6 +188,7 @@
 // missing symbol linker errors on windows.
 #if defined(LLVM_BUILD_STATIC)
 #define LLVM_ABI
+#define LLVM_FRIEND_ABI
 #define LLVM_TEMPLATE_ABI
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT
@@ -196,21 +202,25 @@
 #define LLVM_TEMPLATE_ABI __declspec(dllimport)
 #define LLVM_EXPORT_TEMPLATE
 #endif
+#define LLVM_FRIEND_ABI LLVM_ABI
 #define LLVM_ABI_EXPORT __declspec(dllexport)
 #elif defined(__ELF__) || defined(__MINGW32__) || defined(_AIX) ||             \
     defined(__MVS__)
 #define LLVM_ABI LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
+#define LLVM_FRIEND_ABI
 #define LLVM_TEMPLATE_ABI LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
 #elif defined(__MACH__) || defined(__WASM__) || defined(__EMSCRIPTEN__)
 #define LLVM_ABI LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
+#define LLVM_FRIEND_ABI
 #define LLVM_TEMPLATE_ABI
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
 #endif
 #else
 #define LLVM_ABI
+#define LLVM_FRIEND_ABI
 #define LLVM_TEMPLATE_ABI
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT

``````````

</details>


https://github.com/llvm/llvm-project/pull/136595