[llvm] c049583 - [llvm] add LLVM_ABI_FRIEND macro for friend function decls (#136595)

[via llvm-commits]

Author: Andrew Rogers
Date: 2025-04-22T09:49:18-07:00
New Revision: c04958381e90c32381ddabf1552d17c63cdd060b

URL: https://github.com/llvm/llvm-project/commit/c04958381e90c32381ddabf1552d17c63cdd060b
DIFF: https://github.com/llvm/llvm-project/commit/c04958381e90c32381ddabf1552d17c63cdd060b.diff

LOG: [llvm] add LLVM_ABI_FRIEND macro for friend function decls (#136595)

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

## Overview
1. Add a new `LLVM_ABI_FRIEND` 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_ABI_FRIEND` 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).

Added: 
    

Modified: 
    llvm/docs/InterfaceExportAnnotations.rst
    llvm/include/llvm/Support/Compiler.h

Removed: 
    


################################################################################
diff  --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index eecf6ffe6eaca..581fcd8513185 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_ABI_FRIEND`` 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_ABI_FRIEND 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_ABI_FRIEND``
+   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..4864071ed87a8 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_ABI_FRIEND 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 
diff erent 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_ABI_FRIEND
 #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_ABI_FRIEND 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_ABI_FRIEND
 #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_ABI_FRIEND
 #define LLVM_TEMPLATE_ABI
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT LLVM_ATTRIBUTE_VISIBILITY_DEFAULT
 #endif
 #else
 #define LLVM_ABI
+#define LLVM_ABI_FRIEND
 #define LLVM_TEMPLATE_ABI
 #define LLVM_EXPORT_TEMPLATE
 #define LLVM_ABI_EXPORT