llvm/docs/HowToBuildWindowsItaniumPrograms.rst

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