mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-22 10:42:39 +01:00
Reland: [Docs][Windows Itanium] Add a How-To document for Windows Itanium.
This is a basic How-To that describes: - What Windows Itanium is. - How to assemble a build environment. Differential Revision: https://reviews.llvm.org/D89518
This commit is contained in:
Ben Dunbobbin
parent
9daab338b2
commit
761a3287bd
184
docs/HowToBuildWindowsItaniumPrograms.rst
Normal file
184
docs/HowToBuildWindowsItaniumPrograms.rst
Normal file
@ -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=<path to llvm checkout e.g. /llvm-project/> -DCMAKE_INSTALL_PREFIX=<install path> <other options> <path to project e.g. /llvm-project/libcxxabi>``
|
||||
* ``<make program e.g. ninja>``
|
||||
* ``<make program> 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=<install path>``
|
||||
|
||||
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=<path to libcxx>/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=<libcxxabi src path>/include``
|
||||
* ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=<libcxxabi build 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=<path to installed unwind.lib>``
|
||||
|
||||
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
|
||||
@ -33,6 +33,7 @@ intermediate LLVM representation.
|
||||
GoldPlugin
|
||||
HowToBuildOnARM
|
||||
HowToBuildWithPGO
|
||||
HowToBuildWindowsItaniumPrograms
|
||||
HowToCrossCompileBuiltinsOnArm
|
||||
HowToCrossCompileLLVM
|
||||
HowToUpdateDebugInfo
|
||||
@ -198,6 +199,9 @@ 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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user