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.
