Index: llvm/docs/HowToBuildWindowsItaniumPrograms.rst =================================================================== --- /dev/null +++ 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= -DCMAKE_INSTALL_PREFIX= `` +* ```` +* `` 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=`` + +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=/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=/include`` +* ``-DLIBCXX_CXX_ABI_LIBRARY_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=`` + +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 Index: llvm/docs/UserGuides.rst =================================================================== --- llvm/docs/UserGuides.rst +++ llvm/docs/UserGuides.rst @@ -33,6 +33,7 @@ GoldPlugin HowToBuildOnARM HowToBuildWithPGO + HowToBuildWindowsItaniumPrograms HowToCrossCompileBuiltinsOnArm HowToCrossCompileLLVM HowToUpdateDebugInfo @@ -187,6 +188,9 @@ 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.