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