diff --git a/llvm/docs/HowToBuildWindowsItaniumPrograms.rst b/llvm/docs/HowToBuildWindowsItaniumPrograms.rst deleted file mode 100644 index cad632a812dd..000000000000 --- a/llvm/docs/HowToBuildWindowsItaniumPrograms.rst +++ /dev/null @@ -1,184 +0,0 @@ -========================================== -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 diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst index 665d1bda1bbf..1bdda525cb62 100644 --- a/llvm/docs/UserGuides.rst +++ b/llvm/docs/UserGuides.rst @@ -33,7 +33,6 @@ intermediate LLVM representation. GoldPlugin HowToBuildOnARM HowToBuildWithPGO - HowToBuildWindowsItaniumPrograms HowToCrossCompileBuiltinsOnArm HowToCrossCompileLLVM HowToUpdateDebugInfo @@ -199,9 +198,6 @@ 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.