1========================================== 2How to build Windows Itanium applications. 3========================================== 4 5Introduction 6============ 7 8This document contains information describing how to create a Windows Itanium toolchain. 9 10Windows Itanium allows you to deploy Itanium C++ ABI applications on top of the MS VS CRT. 11This environment can use the Windows SDK headers directly and does not required additional 12headers or additional runtime machinery (such as is used by mingw). 13 14Windows Itanium Stack: 15 16* Uses the Itanium C++ abi. 17* libc++. 18* libc++-abi. 19* libunwind. 20* The MS VS CRT. 21* Is compatible with MS Windows SDK include headers. 22* COFF/PE file format. 23* LLD 24 25Note: compiler-rt is not used. This functionality is supplied by the MS VCRT. 26 27Prerequisites 28============= 29 30* The MS SDK is installed as part of MS Visual Studio. 31* Clang with support for the windows-itanium triple. 32* COFF LLD with support for the -autoimport switch. 33 34Known issues: 35============= 36 37SJLJ exceptions, "-fsjlj-exceptions", are the only currently supported model. 38 39link.exe (the MS linker) is unsuitable as it doesn't support auto-importing which 40is currently required to link correctly. However, if that limitation is removed 41then there are no other known issues with using link.exe. 42 43Currently, there is a lack of a usable Windows compiler driver for Windows Itanium. 44A reasonable work-around is to build clang with a windows-msvc default target and 45then override the triple with e.g. "-Xclang -triple -Xclang x86_64-unknown-windows-itanium". 46The linker can be specified with: "-fuse-ld=lld". 47 48In the Itanium C++ ABI the first member of an object is a pointer to the vtable 49for its class. The vtable is often emitted into the object file with the key function 50and must be imported for classes marked dllimport. The pointers must be globally 51unique. Unfortunately, the COFF/PE file format does not provide a mechanism to 52store a runtime address from another DLL into this pointer (although runtime 53addresses are patched into the IAT). Therefore, the compiler must emit some code, 54that runs after IAT patching but before anything that might use the vtable pointers, 55and sets the vtable pointer to the address from the IAT. For the special case of 56the references to vtables for __cxxabiv1::__class_type_info from typeinto objects 57there is no declaration available to the compiler so this can't be done. To allow 58programs to link we currently rely on the -auto-import switch in LLD to auto-import 59references to __cxxabiv1::__class_type_info pointers (see: https://reviews.llvm.org/D43184 60for a related discussion). This allows for linking; but, code that actually uses 61such fields will not work as they these will not be fixed up at runtime. See 62_pei386_runtime_relocator which handles the runtime component of the autoimporting 63scheme used for mingw and comments in https://reviews.llvm.org/D43184 and 64https://reviews.llvm.org/D89518 for more. 65 66Assembling a Toolchain: 67======================= 68 69The procedure is: 70 71# Build an LLVM toolchain with support for Windows Itanium. 72# Use the toolchain from step 1. to build libc++, libc++abi, and libunwind. 73 74It is also possible to cross-compile from Linux. 75 76To build the libraries in step 2, refer to the `libc++ documentation <https://libcxx.llvm.org/VendorDocumentation.html#the-default-build>`_. 77 78The next section discuss the salient options and modifications required for building and installing the 79libraries. This assumes that we are building libunwind and libc++ as DLLs and statically linking libc++abi 80into libc++. Other build configurations are possible, but they are not discussed here. 81 82Common CMake configuration options: 83----------------------------------- 84 85* ``-D_LIBCPP_ABI_FORCE_ITANIUM'`` 86 87Tell the libc++ headers that the Itanium C++ ABI is being used. 88 89* ``-DCMAKE_C_FLAGS="-lmsvcrt -llegacy_stdio_definitions -D_NO_CRT_STDIO_INLINE"`` 90 91Supply CRT definitions including stdio definitions that have been removed from the MS VS CRT. 92We don't want the stdio functions declared inline as they will cause multiple definition 93errors when the same symbols are pulled in from legacy_stdio_definitions.ib. 94 95* ``-DCMAKE_INSTALL_PREFIX=<install path>`` 96 97Where to install the library and headers. 98 99Building libunwind: 100------------------- 101 102* ``-DLIBUNWIND_ENABLE_SHARED=ON`` 103* ``-DLIBUNWIND_ENABLE_STATIC=OFF`` 104 105libunwind can be built as a DLL. It is not dependent on other projects. 106 107* ``-DLIBUNWIND_USE_COMPILER_RT=OFF`` 108 109We use the MS runtime. 110 111The CMake files will need to be edited to prevent them adding GNU specific libraries to the link line. 112 113Building libc++abi: 114------------------- 115 116* ``-DLIBCXXABI_ENABLE_SHARED=OFF`` 117* ``-DLIBCXXABI_ENABLE_STATIC=ON`` 118* ``-DLIBCXX_ENABLE_SHARED=ON'`` 119* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON`` 120 121To break the symbol dependency between libc++abi and libc++ we 122build libc++abi as a static library and then statically link it 123into the libc++ DLL. This necessitates setting the CMake file 124to ensure that the visibility macros (which expand to dllexport/import) 125are expanded as they will be needed when creating the final libc++ 126DLL later, see: https://reviews.llvm.org/D90021. 127 128* ``-DLIBCXXABI_LIBCXX_INCLUDES=<path to libcxx>/include`` 129 130Where to find the libc++ headers 131 132Building libc++: 133---------------- 134 135* ``-DLIBCXX_ENABLE_SHARED=ON`` 136* ``-DLIBCXX_ENABLE_STATIC=OFF`` 137 138We build libc++ as a DLL and statically link libc++abi into it. 139 140* ``-DLIBCXX_INSTALL_HEADERS=ON`` 141 142Install the headers. 143 144* ``-DLIBCXX_USE_COMPILER_RT=OFF`` 145 146We use the MS runtime. 147 148* ``-DLIBCXX_HAS_WIN32_THREAD_API=ON`` 149 150Windows Itanium does not offer a POSIX-like layer over WIN32. 151 152* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON`` 153* ``-DLIBCXX_CXX_ABI=libcxxabi`` 154* ``-DLIBCXX_CXX_ABI_INCLUDE_PATHS=<libcxxabi src path>/include`` 155* ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=<libcxxabi build path>/lib`` 156 157Use the static libc++abi library built earlier. 158 159* ``-DLIBCXX_NO_VCRUNTIME=ON`` 160 161Remove any dependency on the VC runtime - we need libc++abi to supply the C++ runtime. 162 163* ``-DCMAKE_C_FLAGS=<path to installed unwind.lib>`` 164 165As we are statically linking against libcxxabi we need to link 166against the unwind import library to resolve unwind references 167from the libcxxabi objects. 168 169* ``-DCMAKE_C_FLAGS+=' -UCLOCK_REALTIME'`` 170 171Prevent the inclusion of sys/time that MS doesn't provide. 172 173Notes: 174------ 175 176An example build recipe is available here: https://reviews.llvm.org/D88124 177