177 lines · plain
1==========================================2How to build Windows Itanium applications.3==========================================4 5Introduction6============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 require additional12headers 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* LLD24 25Note: compiler-rt is not used. This functionality is supplied by the MS VCRT.26 27Prerequisites28=============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 which40is currently required to link correctly. However, if that limitation is removed41then 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 and45then 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 vtable49for its class. The vtable is often emitted into the object file with the key function50and must be imported for classes marked dllimport. The pointers must be globally51unique. Unfortunately, the COFF/PE file format does not provide a mechanism to52store a runtime address from another DLL into this pointer (although runtime53addresses 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 of56the references to vtables for __cxxabiv1::__class_type_info from typeinto objects57there is no declaration available to the compiler so this can't be done. To allow58programs to link we currently rely on the -auto-import switch in LLD to auto-import59references to __cxxabiv1::__class_type_info pointers (see: https://reviews.llvm.org/D4318460for a related discussion). This allows for linking; but, code that actually uses61such fields will not work as they these will not be fixed up at runtime. See62_pei386_runtime_relocator which handles the runtime component of the autoimporting63scheme used for mingw and comments in https://reviews.llvm.org/D43184 and64https://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 discusses the salient options and modifications required for building and installing the79libraries. This assumes that we are building libunwind and libc++ as DLLs and statically linking libc++abi80into 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 definition93errors 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++ we122build libc++abi as a static library and then statically link it123into the libc++ DLL. This necessitates setting the CMake file124to 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++ headers131 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 link166against the unwind import library to resolve unwind references167from 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/D88124177