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

[Vassil Vassilev 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,
----------------
vgvassilev wrote:

Probably also worth saying what elf, mach-o and coff is in a succinct form.

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