[Docs][Windows Itanium] Add a How-To document for Windows Itanium.

This is a basic How-To that describes:
- What Windows Itanium is.
- How to assemble a build environment.

Differential Revision: https://reviews.llvm.org/D89518

Author: bd1976bris

llvm/docs/HowToBuildWindowsItaniumPrograms.rst

@@ -0,0 +1,184 @@
+==========================================
+How to build Windows Itanium applications.
+==========================================
+
+Introduction
+============
+
+This document contains information describing how to create a Windows Itanium toolchain.
+
+Windows Itanium allows you to deploy Itanium C++ ABI applications on top of the MS VS CRT.
+This environment can use the Windows SDK headers directly and does not required additional
+headers or additional runtime machinery (such as is used by mingw).
+
+Windows Itanium Stack:
+
+* Uses the Itanium C++ abi.
+* libc++.
+* libc++-abi.
+* libunwind.
+* The MS VS CRT.
+* Is compatible with MS Windows SDK include headers.
+* COFF/PE file format.
+* LLD
+
+Note: compiler-rt is not used. This functionality is supplied by the MS VCRT.
+
+Prerequisites
+=============
+
+* The MS SDK is installed as part of MS Visual Studio.
+* Clang with support for the windows-itanium triple.
+* COFF LLD with support for the -autoimport switch.
+
+Known issues:
+=============
+
+SJLJ exceptions, "-fsjlj-exceptions", are the only currently supported model.
+
+link.exe (the MS linker) is unsuitable as it doesn't support auto-importing which
+is currently required to link correctly. However, if that limitation is removed
+then there are no other known issues with using link.exe.
+
+Currently, there is a lack of a usable Windows compiler driver for Windows Itanium.
+A reasonable work-around is to build clang with a windows-msvc default target and
+then override the triple with e.g. "-Xclang -triple -Xclang x86_64-unknown-windows-itanium".
+The linker can be specified with: "-fuse-ld=lld".
+
+In the Itanium C++ ABI the first member of an object is a pointer to the vtable
+for its class. The vtable is often emitted into the object file with the key function
+and must be imported for classes marked dllimport. The pointers must be globally
+unique. Unfortunately, the COFF/PE file format does not provide a mechanism to 
+store a runtime address from another DLL into this pointer (although runtime
+addresses are patched into the IAT). Therefore, the compiler must emit some code,
+that runs after IAT patching but before anything that might use the vtable pointers,
+and sets the vtable pointer to the address from the IAT. For the special case of
+the references to vtables for __cxxabiv1::__class_type_info from typeinto objects
+there is no declaration available to the compiler so this can't be done. To allow
+programs to link we currently rely on the -auto-import switch in LLD to auto-import
+references to __cxxabiv1::__class_type_info pointers (see: https://reviews.llvm.org/D43184
+for a related discussion). This allows for linking; but, code that actually uses
+such fields will not work as they these will not be fixed up at runtime. See 
+_pei386_runtime_relocator which handles the runtime component of the autoimporting
+scheme used for mingw and comments in https://reviews.llvm.org/D43184 and
+https://reviews.llvm.org/D89518 for more.
+
+Assembling a Toolchain:
+=======================
+
+The procedure is:
+
+# Build an LLVM toolchain with support for Windows Itanium.
+# Use the toolchain from step 1. to build libc++, libc++abi, and libunwind.
+
+It is also possible to cross-compile from Linux.
+
+One method of building the libraries in step 2. is to build them "stand-alone".
+A stand-alone build doesn't involve the rest of the LLVM tree. The steps are:
+
+* ``cd build-dir``
+* ``cmake -DLLVM_PATH=<path to llvm checkout e.g. /llvm-project/> -DCMAKE_INSTALL_PREFIX=<install path> <other options> <path to project e.g. /llvm-project/libcxxabi>``
+* ``<make program e.g. ninja>``
+* ``<make program> install``
+
+More information on standalone builds can be found in the build documentation for
+the respective libraries. The next section discuss the salient options and modifications
+required for building and installing the libraries using standalone builds. This assumes
+that we are building libunwind and ibc++ as DLLs and statically linking libc++abi into
+libc++. Other build configurations are possible, but they are not discussed here.
+
+Common CMake configuration options:
+-----------------------------------
+
+* ``-D_LIBCPP_ABI_FORCE_ITANIUM'``
+
+Tell the libc++ headers that the Itanium C++ ABI is being used.
+
+* ``-DCMAKE_C_FLAGS="-lmsvcrt -llegacy_stdio_definitions -D_NO_CRT_STDIO_INLINE"``
+
+Supply CRT definitions including stdio definitions that have been removed from the MS VS CRT.
+We don't want the stdio functions decalred inline as they will casuse multiple defintiion
+errors when the same symbols are pulled in from legacy_stdio_definitions.ib.
+
+* ``-DCMAKE_INSTALL_PREFIX=<install path>``
+
+Where to install the library and headers.
+
+Building libunwind:
+-------------------
+
+* ``-DLIBUNWIND_ENABLE_SHARED=ON``
+* ``-DLIBUNWIND_ENABLE_STATIC=OFF``
+
+libunwind can be built as a DLL. It is not dependent on other projects.
+
+* ``-DLIBUNWIND_USE_COMPILER_RT=OFF``
+
+We use the MS runtime.
+
+The CMake files will need to be edited to prevent them adding GNU specific libraries to the link line.
+
+Building libc++abi:
+------------------
+
+* ``-DLIBCXXABI_ENABLE_SHARED=OFF``
+* ``-DLIBCXXABI_ENABLE_STATIC=ON``
+* ``-DLIBCXX_ENABLE_SHARED=ON'``
+* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON``
+
+To break the symbol dependency between libc++abi and libc++ we
+build libc++abi as a static library and then statically link it
+into the libc++ DLL. This necessitates setting the CMake file
+to ensure that the visibility macros (which expand to dllexport/import)
+are expanded as they will be needed when creating the final libc++
+DLL later, see: https://reviews.llvm.org/D90021.
+
+* ``-DLIBCXXABI_LIBCXX_INCLUDES=<path to libcxx>/include``
+
+Where to find the libc++ headers
+
+Building libc++:
+----------------
+
+* ``-DLIBCXX_ENABLE_SHARED=ON``
+* ``-DLIBCXX_ENABLE_STATIC=OFF``
+
+We build libc++ as a DLL and statically link libc++abi into it.
+
+* ``-DLIBCXX_INSTALL_HEADERS=ON``
+
+Install the headers.
+
+* ``-DLIBCXX_USE_COMPILER_RT=OFF``
+
+We use the MS runtime.
+
+* ``-DLIBCXX_HAS_WIN32_THREAD_API=ON``
+
+Windows Itanium does not offer a POSIX-like layer over WIN32.
+
+* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON``
+* ``-DLIBCXX_CXX_ABI=libcxxabi``
+* ``-DLIBCXX_CXX_ABI_INCLUDE_PATHS=<libcxxabi src path>/include``
+* ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=<libcxxabi build path>/lib``
+
+Use the static libc++abi library built earlier.
+
+* ``-DLIBCXX_NO_VCRUNTIME=ON``
+
+Remove any dependency on the VC runtime - we need libc++abi to supply the C++ runtime.
+
+* ``-DCMAKE_C_FLAGS=<path to installed unwind.lib>``
+
+As we are statically linking against libcxxabi we need to link
+against the unwind import library to resolve unwind references
+from the libcxxabi objects.
+
+* ``-DCMAKE_C_FLAGS+=' -UCLOCK_REALTIME'``
+
+Prevent the inclusion of sys/time that MS doesn't provide.
+
+Notes:
+------
+
+An example build recipe is available here: https://reviews.llvm.org/D88124

llvm/docs/UserGuides.rst

@@ -33,6 +33,7 @@ intermediate LLVM representation.
    GoldPlugin
    HowToBuildOnARM
    HowToBuildWithPGO
+   HowToBuildWindowsItaniumPrograms
    HowToCrossCompileBuiltinsOnArm
    HowToCrossCompileLLVM
    HowToUpdateDebugInfo
@@ -198,6 +199,9 @@ Additional Topics
    Gives the steps necessary when adding a new constrained math intrinsic
    to LLVM.
 
+:doc:`HowToBuildWindowsItaniumPrograms`
+   Notes on assembling a Windows Itanium enviroment.
+
 :doc:`HowToCrossCompileBuiltinsOnArm`
    Notes on cross-building and testing the compiler-rt builtins for Arm.