[llvm] [llvm] add documentation for public interface annotations (LLVM_ABI, etc) (PR #134710)
Andrew Rogers via llvm-commits
llvm-commits at lists.llvm.org
Wed Apr 9 08:07:14 PDT 2025
https://github.com/andrurogerz updated https://github.com/llvm/llvm-project/pull/134710
>From 8d637e38f5613ad79839a9524bd82bf8de2bd615 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Mon, 7 Apr 2025 10:48:33 -0700
Subject: [PATCH 1/7] [llvm] add docs for interface annotations (LLVM_ABI, etc)
---
llvm/docs/InterfaceExportAnnotations.rst | 277 +++++++++++++++++++++++
1 file changed, 277 insertions(+)
create mode 100644 llvm/docs/InterfaceExportAnnotations.rst
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
new file mode 100644
index 0000000000000..53643c5b06cd4
--- /dev/null
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -0,0 +1,277 @@
+LLVM Interface Export Annotations
+=================================
+
+With the following build settings, LLVM will be built as a shared library with
+hidden default symbol visibility:
+
+::
+
+ LLVM_BUILD_LLVM_DYLIB_VIS=On
+ LLVM_BUILD_LLVM_DYLIB=On
+ LLVM_LINK_LLVM_DYLIB=On
+
+When building LLVM in this configuration, any symbol intended to be visible to
+clients must be explicitly exported.
+
+Exporting a symbol typically requires annotating it with the ``LLVM_ABI`` macro
+defined in `compiler.h
+<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/Compiler.h#L152>`__.
+There are similar annotations that must be used in a few special cases. This
+document describes the common patterns for annotating LLVM symbols for export.
+
+Functions
+---------
+
+Exported function declarations in header files must be annotated with
+``LLVM_ABI``.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ LLVM_ABI void exported_function(int a, int b);
+
+Global Variables
+----------------
+
+Exported global variables must be annotated with ``LLVM_ABI`` at their
+``extern`` declarations.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ LLVM_ABI extern int exported_global_variable;
+
+Classes, Structs, and Unions
+----------------------------
+
+Classes, structs, and unions can be annotated with ``LLVM_ABI`` at their
+definition, but this option is generally discouraged. Annotating the entire
+definition exports unnecessary symbols, such as private functions, vtables, and
+type information. Instead, ``LLVM_ABI`` should be applied only to public and
+protected method declarations without a body in the header, including
+constructors and destructors.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ class ExampleClass {
+ public:
+ // Public methods defined externally must be annotatated.
+ LLVM_ABI int sourceDefinedPublicMethod(int a, int b);
+
+ // Methods defined in the class definition do not need annotation.
+ int headerDefinedPublicMethod(int a, int b) {
+ return a + b;
+ }
+
+ // Constructors and destructors must be annotated if defined externally.
+ ExampleClass() {}
+ LLVM_ABI ~ExampleClass();
+
+ // Public static methods defined externally must be annotatated.
+ LLVM_ABI static int sourceDefinedPublicStaticMethod(int a, int b);
+ };
+
+Additionally, public and protected static fields that are not initialized at
+declaration must be annotated with ``LLVM_ABI``.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ class ExampleClass {
+ public:
+ // Public static fields defined externally must be annotated.
+ LLVM_ABI static int mutableStaticField;
+ LLVM_ABI static const int constStaticField;
+
+ // Static members initialized at declaration do not need to be annotated.
+ static const int initializedConstStaticField = 0;
+ static constexpr int initializedConstexprStaticField = 0;
+ };
+
+Private methods may also require ``LLVM_ABI`` annotation in certain cases. This
+situation occurs when a method defined in a header calls the private method. The
+private method call may be from within the class, a parent class, or a friend
+class.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ class ExampleClass {
+ private:
+ // Private methods must be annotated if referenced by a public method defined a
+ // header file.
+ LLVM_ABI int privateMethod(int a, int b);
+
+ public:
+ // Inlineable method defined in the class definition calls a private method
+ // defined externally. If the private method is not annotated for export, this
+ // method will fail to link.
+ int publicMethod(int a, int b) {
+ return privateMethod(a, b);
+ }
+ };
+
+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``.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ // An exported function that has friend access to ExampleClass internals.
+ LLVM_ABI int friend_function(ExampleClass &obj);
+
+ 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);
+ };
+
+.. 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.
+
+VTable and Type Info
+--------------------
+
+Classes and structs with exported virtual methods, or child classes that export
+overridden virtual methods, must also export their vtable for ELF and Mach-O
+builds. This can be achieved by annotating the class rather than individual
+class members.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ class ParentClass {
+ public:
+ virtual int virtualMethod(int a, int b);
+ virtual int anotherVirtualMethod(int a, int b);
+ virtual ~ParentClass();
+ };
+
+ // Annotating the class exports vtable and type information as well as all
+ // class members.
+ class LLVM_ABI ChildClass : public ParentClass {
+ public:
+ // Inline method override does not require the class be annotated.
+ int virtualMethod(int a, int b) override {
+ return ParentClass::virtualMethod(a, b);
+ }
+
+ // Overriding a virtual method from the parent requires the class be
+ // annotated. The parent class may require annotation as well.
+ int pureVirtualMethod(int a, int b) override;
+ ~ChildClass();
+ };
+
+If annotating a type with ``LLVM_ABI`` causes compilation issues such as those
+described
+`here <https://devblogs.microsoft.com/oldnewthing/20190927-00/?p=102932>`__,
+the class may require modification. Often, explicitly deleting the copy
+constructor and copy assignment operator will resolve the issue.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ #include <vector>
+
+ class LLVM_ABI ExportedClass {
+ public:
+ // Explicitly delete the copy constructor and assignment operator.
+ ExportedClass(ExportedClass const&) = delete;
+ ExportedClass& operator=(ExportedClass const&) = delete;
+ };
+
+Templates
+---------
+
+Most template classes are entirely header-defined and do not need to be exported
+because they will be instantiated and compiled into the client as needed. Such
+template classes require no export annotations. However, there are some less
+common cases where annotations are required for templates.
+
+Specialized Template Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As with any other exported function, an exported specialization of a template
+function not defined in a header file must have its declaration annotated with
+``LLVM_ABI``.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ template <typename T> T templateMethod(T a, T b) {
+ return a + b;
+ }
+
+ // The explicitly specialized definition of templateMethod for int is located in
+ // a source file. This declaration must be annotated with LLVM_ABI to export it.
+ template <> LLVM_ABI int templateMethod(int a, int b);
+
+Similarly, an exported specialization of a method in a template class must have
+its declaration annotated with ``LLVM_ABI``.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ template <typename T> class TemplateClass {
+ public:
+ int method(int a, int b) {
+ return a + b;
+ }
+ };
+
+ // The explicitly specialized definition of method for int is defined in a
+ // source file. The declaration must be annotated with LLVM_ABI to export it.
+ template <> LLVM_ABI int TemplateStruct<int>::method(int a, int b);
+
+Explicitly Instantiated Template Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Explicitly instantiated template classes must be annotated with
+template-specific annotations at both declaration and definition.
+
+An extern template instantiation in a header file must be annotated with
+``LLVM_TEMPLATE_ABI``. This will typically be located in a header file.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ template <typename T> class TemplateClass {
+ public:
+ TemplateClass(T val) : val_(val) {}
+
+ T get() const { return val_; }
+
+ private:
+ const T val_;
+ };
+
+ // Explicitly instantiate and export TempalateClass for int type.
+ extern template class LLVM_TEMPLATE_ABI TemplateClass<int>;
+
+The corresponding definition of the template instantiation must be annotated
+with ``LLVM_EXPORT_TEMPLATE``. This will typically be located in a source file.
+
+.. code:: cpp
+
+ #include "TemplateClass.h"
+
+ // Explicitly instantiate and export TempalateClass for int type.
+ template class LLVM_EXPORT_TEMPLATE TemplateClass<int>;
>From 01ce75be8f5fe7146f17c133630695f52113d948 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Mon, 7 Apr 2025 12:30:58 -0700
Subject: [PATCH 2/7] [llvm] include interface export annotation doc in hidden
toc
---
llvm/docs/Reference.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/llvm/docs/Reference.rst b/llvm/docs/Reference.rst
index 470b6bd024b89..e1f46b00f2b30 100644
--- a/llvm/docs/Reference.rst
+++ b/llvm/docs/Reference.rst
@@ -31,6 +31,7 @@ LLVM and API reference documentation.
HowToSetUpLLVMStyleRTTI
HowToUseAttributes
InAlloca
+ InterfaceExportAnnotations
LangRef
LibFuzzer
MarkedUpDisassembly
>From 74fba7961ceb80662c27dae98e5b9ad40a21a775 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Mon, 7 Apr 2025 15:39:39 -0700
Subject: [PATCH 3/7] add introduction with more details and context
---
llvm/docs/InterfaceExportAnnotations.rst | 89 +++++++++++++++++++-----
1 file changed, 72 insertions(+), 17 deletions(-)
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index 53643c5b06cd4..f3f983755d982 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -1,26 +1,80 @@
LLVM Interface Export Annotations
=================================
-With the following build settings, LLVM will be built as a shared library with
-hidden default symbol visibility:
+Symbols that are part of LLVM's public interface must be explicitly annotated
+to support shared library builds with hidden default symbol visibility. This
+document provides background and guidelines for annotating the codebase.
+
+LLVM Shared Library
+-------------------
+LLVM builds as a static library by default, but it can also be built as a shared
+library with the following configuration:
::
- LLVM_BUILD_LLVM_DYLIB_VIS=On
LLVM_BUILD_LLVM_DYLIB=On
LLVM_LINK_LLVM_DYLIB=On
-When building LLVM in this configuration, any symbol intended to be visible to
-clients must be explicitly exported.
+For ELF and Mach-O builds, this configuration works as-is because all symbols
+are exported by default. To build a Windows DLL, however, the situation is more
+complex:
+
+- Symbols are not exported from a DLL by default. Symbols must be annotated with
+ ``__declspec(dllexport)`` when building the library to be externally visible.
+
+- Symbols imported from a Windows DLL should generally be annotated with
+ ``__declspec(dllimport)`` when compiling clients.
+
+- A single Windows DLL can export a maximum of 65,535 symbols.
+
+Annotation Macros
+-----------------
+The distinct DLL import and export annotations required for Windows DLLs
+typically lead developers to define a preprocessor macro for annotating exported
+symbols in header public files. The custom macro resolves to the _export_
+annotation when building the library and the _import_ annotation when building
+the client.
-Exporting a symbol typically requires annotating it with the ``LLVM_ABI`` macro
-defined in `compiler.h
+For this purpose, we have defined the `LLVM_ABI` macro in
+`llvm/Support/Compiler.h
<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/Compiler.h#L152>`__.
-There are similar annotations that must be used in a few special cases. This
-document describes the common patterns for annotating LLVM symbols for export.
+
+.. code:: cpp
+
+ #if defined(LLVM_EXPORTS)
+ #define LLVM_ABI __declspec(dllexport)
+ #else
+ #define LLVM_ABI __declspec(dllimport)
+ #endif
+
+Because building LLVM for Windows is less common than ELF and Mach-O platforms,
+Windows DLL symbol visibility requirements are approximated on these platforms
+by setting default symbol visibility to hidden
+(``-fvisibility-default=hidden``) when building with the following
+configuration:
+
+::
+
+ LLVM_BUILD_LLVM_DYLIB_VIS=On
+
+For an ELF or Mach-O platform with this setting, the ``LLVM_ABI`` macro is
+defined to override the default hidden symbol visibility:
+
+.. code:: cpp
+
+ #define LLVM_ABI __attribute__((visibility("default")))
+
+In addition to ``LLVM_ABI``, there are a few other macros for use in less
+common cases described below. All ``LLVM_`` export macros are only for use with
+symbols defined in the LLVM library. They must not be used to annotate symbols
+defined in other LLVM projects such as lld, lldb, and clang. Their use should
+generally restricted to source code under ``llvm-project/llvm``.
+
+Annotating Symbols
+------------------
Functions
----------
+~~~~~~~~~
Exported function declarations in header files must be annotated with
``LLVM_ABI``.
@@ -32,7 +86,7 @@ Exported function declarations in header files must be annotated with
LLVM_ABI void exported_function(int a, int b);
Global Variables
-----------------
+~~~~~~~~~~~~~~~~
Exported global variables must be annotated with ``LLVM_ABI`` at their
``extern`` declarations.
@@ -44,7 +98,7 @@ Exported global variables must be annotated with ``LLVM_ABI`` at their
LLVM_ABI extern int exported_global_variable;
Classes, Structs, and Unions
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Classes, structs, and unions can be annotated with ``LLVM_ABI`` at their
definition, but this option is generally discouraged. Annotating the entire
@@ -118,7 +172,7 @@ class.
};
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
@@ -138,12 +192,13 @@ requirement applies even when the class itself is annotated with ``LLVM_ABI``.
};
.. 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.
VTable and Type Info
---------------------
+~~~~~~~~~~~~~~~~~~~~
Classes and structs with exported virtual methods, or child classes that export
overridden virtual methods, must also export their vtable for ELF and Mach-O
@@ -196,7 +251,7 @@ constructor and copy assignment operator will resolve the issue.
};
Templates
----------
+~~~~~~~~~
Most template classes are entirely header-defined and do not need to be exported
because they will be instantiated and compiled into the client as needed. Such
@@ -204,7 +259,7 @@ template classes require no export annotations. However, there are some less
common cases where annotations are required for templates.
Specialized Template Functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
As with any other exported function, an exported specialization of a template
function not defined in a header file must have its declaration annotated with
@@ -241,7 +296,7 @@ its declaration annotated with ``LLVM_ABI``.
template <> LLVM_ABI int TemplateStruct<int>::method(int a, int b);
Explicitly Instantiated Template Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++
Explicitly instantiated template classes must be annotated with
template-specific annotations at both declaration and definition.
>From 5272f5d4329796cc7c09494a0e6897764640a4d7 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Mon, 7 Apr 2025 15:40:33 -0700
Subject: [PATCH 4/7] class declaration instead of class definition, per PR
feedback
---
llvm/docs/InterfaceExportAnnotations.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index f3f983755d982..26480fec6cdd3 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -101,8 +101,8 @@ Classes, Structs, and Unions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Classes, structs, and unions can be annotated with ``LLVM_ABI`` at their
-definition, but this option is generally discouraged. Annotating the entire
-definition exports unnecessary symbols, such as private functions, vtables, and
+declaration, but this option is generally discouraged. Annotating the entire
+class exports unnecessary symbols, such as private functions, vtables, and
type information. Instead, ``LLVM_ABI`` should be applied only to public and
protected method declarations without a body in the header, including
constructors and destructors.
>From 3bc67d77c6c8ccc6b5ea8ed20ce6564af9ae34cd Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Tue, 8 Apr 2025 17:33:03 -0700
Subject: [PATCH 5/7] incorporate PR feedback
---
llvm/docs/InterfaceExportAnnotations.rst | 100 ++++++++++++++++-------
1 file changed, 72 insertions(+), 28 deletions(-)
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index 26480fec6cdd3..26ea2165fd272 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -1,6 +1,5 @@
LLVM Interface Export Annotations
=================================
-
Symbols that are part of LLVM's public interface must be explicitly annotated
to support shared library builds with hidden default symbol visibility. This
document provides background and guidelines for annotating the codebase.
@@ -15,9 +14,14 @@ library with the following configuration:
LLVM_BUILD_LLVM_DYLIB=On
LLVM_LINK_LLVM_DYLIB=On
-For ELF and Mach-O builds, this configuration works as-is because all symbols
-are exported by default. To build a Windows DLL, however, the situation is more
-complex:
+There are three shared library executable formats we're interested in: PE
+Dynamic Link Library (.DLL) on Windows, Mach-O Shared Object (.dylib) on Apple
+systems, and ELF Shared Object (.so) on Linux, BSD and other Unix-like systems.
+
+ELF and Mach-O Shared Object files can be built with no additional setup or
+configuration. This is because all global symbols in the library are exported by
+default-- the same as when building a static library. However, when building a
+DLL for Windows, the situation is more complex:
- Symbols are not exported from a DLL by default. Symbols must be annotated with
``__declspec(dllexport)`` when building the library to be externally visible.
@@ -27,6 +31,9 @@ complex:
- A single Windows DLL can export a maximum of 65,535 symbols.
+Because of the requirements for Windows DLLs, additional work must be done to
+ensure the proper set of public symbols is exported and visible to clients.
+
Annotation Macros
-----------------
The distinct DLL import and export annotations required for Windows DLLs
@@ -35,9 +42,9 @@ symbols in header public files. The custom macro resolves to the _export_
annotation when building the library and the _import_ annotation when building
the client.
-For this purpose, we have defined the `LLVM_ABI` macro in
-`llvm/Support/Compiler.h
-<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/Compiler.h#L152>`__.
+We have defined the `LLVM_ABI` macro in `llvm/Support/Compiler.h
+<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/Compiler.h#L152>`__
+for this purpose:
.. code:: cpp
@@ -47,9 +54,8 @@ For this purpose, we have defined the `LLVM_ABI` macro in
#define LLVM_ABI __declspec(dllimport)
#endif
-Because building LLVM for Windows is less common than ELF and Mach-O platforms,
-Windows DLL symbol visibility requirements are approximated on these platforms
-by setting default symbol visibility to hidden
+Windows DLL symbol visibility requirements are approximated on ELF and Mach-O
+shared library builds by setting default symbol visibility to hidden
(``-fvisibility-default=hidden``) when building with the following
configuration:
@@ -65,17 +71,22 @@ defined to override the default hidden symbol visibility:
#define LLVM_ABI __attribute__((visibility("default")))
In addition to ``LLVM_ABI``, there are a few other macros for use in less
-common cases described below. All ``LLVM_`` export macros are only for use with
-symbols defined in the LLVM library. They must not be used to annotate symbols
-defined in other LLVM projects such as lld, lldb, and clang. Their use should
-generally restricted to source code under ``llvm-project/llvm``.
+common cases described below.
+
+Export macros are used to annotate symbols only within their intended shared
+library. This is necessary because of the way Windows handles import/export
+annotations.
+
+For example, ``LLVM_ABI`` resolves to ``__declspec(dllexport)`` only when
+building source that is part of the LLVM shared library (e.g. source under
+``llvm-project/llvm``). If ``LLVM_ABI`` were incorrectly used to annotate a
+symbol from a different LLVM project (such as Clang) it would always resolve to
+``__declspec(dllimport)`` and the symbol would not be properly exported.
Annotating Symbols
------------------
-
Functions
~~~~~~~~~
-
Exported function declarations in header files must be annotated with
``LLVM_ABI``.
@@ -87,7 +98,6 @@ Exported function declarations in header files must be annotated with
Global Variables
~~~~~~~~~~~~~~~~
-
Exported global variables must be annotated with ``LLVM_ABI`` at their
``extern`` declarations.
@@ -99,13 +109,13 @@ Exported global variables must be annotated with ``LLVM_ABI`` at their
Classes, Structs, and Unions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
Classes, structs, and unions can be annotated with ``LLVM_ABI`` at their
-declaration, but this option is generally discouraged. Annotating the entire
-class exports unnecessary symbols, such as private functions, vtables, and
-type information. Instead, ``LLVM_ABI`` should be applied only to public and
-protected method declarations without a body in the header, including
-constructors and destructors.
+declaration, but this option is generally discouraged because it will
+export every class member, vtable, and type information. Instead, ``LLVM_ABI``
+should be applied to individual class members that require export.
+
+In the most common case, public and protected methods without a body in the
+class declaration must be annotated with ``LLVM_ABI``.
.. code:: cpp
@@ -171,9 +181,47 @@ class.
}
};
+There are less common cases where you may also need to annotate an inline
+function even though it is fully defined in a header. Annotating an inline
+function for export does not prevent it being inlined into client code. However,
+it does ensure there is a single, stable address for the function exported from
+the shared library.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ // Annotate the function so it is exported from the library at a fixed
+ // address.
+ LLVM_ABI inline int inlineFunction(int a, int b) {
+ return a + b;
+ }
+
+Similarly, if a stable pointer-to-member function address is required for a
+method in a C++ class, it may be annotated for export.
+
+.. code:: cpp
+
+ #include "llvm/Support/Compiler.h"
+
+ class ExampleClass {
+ public:
+ // Annotate the method so it is exported from the library at a fixed
+ // address.
+ LLVM_ABI inline int inlineMethod(int a, int b) {
+ return a + b;
+ }
+ };
+
+.. note::
+
+ When an inline function is annotated for export, the header containing the
+ function definition **must** be included by at least one of the library's
+ source files or the function will never be compiled with the export
+ annotation.
+
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``.
@@ -199,7 +247,6 @@ requirement applies even when the class itself is annotated with ``LLVM_ABI``.
VTable and Type Info
~~~~~~~~~~~~~~~~~~~~
-
Classes and structs with exported virtual methods, or child classes that export
overridden virtual methods, must also export their vtable for ELF and Mach-O
builds. This can be achieved by annotating the class rather than individual
@@ -252,7 +299,6 @@ constructor and copy assignment operator will resolve the issue.
Templates
~~~~~~~~~
-
Most template classes are entirely header-defined and do not need to be exported
because they will be instantiated and compiled into the client as needed. Such
template classes require no export annotations. However, there are some less
@@ -260,7 +306,6 @@ common cases where annotations are required for templates.
Specialized Template Functions
++++++++++++++++++++++++++++++
-
As with any other exported function, an exported specialization of a template
function not defined in a header file must have its declaration annotated with
``LLVM_ABI``.
@@ -297,7 +342,6 @@ its declaration annotated with ``LLVM_ABI``.
Explicitly Instantiated Template Classes
++++++++++++++++++++++++++++++++++++++++
-
Explicitly instantiated template classes must be annotated with
template-specific annotations at both declaration and definition.
>From 38a63142c7248d8aef8ea2b149120254954f60d9 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Wed, 9 Apr 2025 08:06:39 -0700
Subject: [PATCH 6/7] Update llvm/docs/InterfaceExportAnnotations.rst
Co-authored-by: Saleem Abdulrasool <compnerd at compnerd.org>
---
llvm/docs/InterfaceExportAnnotations.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index 26ea2165fd272..cbabe3e4ca561 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -15,7 +15,7 @@ library with the following configuration:
LLVM_LINK_LLVM_DYLIB=On
There are three shared library executable formats we're interested in: PE
-Dynamic Link Library (.DLL) on Windows, Mach-O Shared Object (.dylib) on Apple
+Dynamic Link Library (.dll) on Windows, Mach-O Shared Object (.dylib) on Apple
systems, and ELF Shared Object (.so) on Linux, BSD and other Unix-like systems.
ELF and Mach-O Shared Object files can be built with no additional setup or
>From f818739823218e800a72715b181efeae829a5e53 Mon Sep 17 00:00:00 2001
From: Andrew Rogers <andrurogerz at gmail.com>
Date: Wed, 9 Apr 2025 08:06:51 -0700
Subject: [PATCH 7/7] Update llvm/docs/InterfaceExportAnnotations.rst
Co-authored-by: Saleem Abdulrasool <compnerd at compnerd.org>
---
llvm/docs/InterfaceExportAnnotations.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/InterfaceExportAnnotations.rst b/llvm/docs/InterfaceExportAnnotations.rst
index cbabe3e4ca561..bc452e421b9ed 100644
--- a/llvm/docs/InterfaceExportAnnotations.rst
+++ b/llvm/docs/InterfaceExportAnnotations.rst
@@ -20,7 +20,7 @@ systems, and ELF Shared Object (.so) on Linux, BSD and other Unix-like systems.
ELF and Mach-O Shared Object files can be built with no additional setup or
configuration. This is because all global symbols in the library are exported by
-default-- the same as when building a static library. However, when building a
+default -- the same as when building a static library. However, when building a
DLL for Windows, the situation is more complex:
- Symbols are not exported from a DLL by default. Symbols must be annotated with
More information about the llvm-commits
mailing list