add introduction with more details and context

Author: andrurogerz

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,15 +251,15 @@ 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
 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.