[llvm] [llvm] add documentation for public interface annotations (LLVM_ABI, etc) (PR #134710)

[Andrew Rogers via llvm-commits]

================
@@ -0,0 +1,332 @@
+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.
+
+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=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:
+
+- 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.
+
+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>`__.
+
+.. 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``.
----------------
andrurogerz wrote:

> _if we were to split up LLVM into LLVM.dll and LLVMSupport.dll, we would need two different macros_

How about something like this?

> 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 shared libraries.

> 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.

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