Skip to content

Commit 5a91d23

Browse files
committed
[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
1 parent 3f3f88f commit 5a91d23

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed
Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
==========================================
2+
How to build Windows Itanium applications.
3+
==========================================
4+
5+
Introduction
6+
============
7+
8+
This document contains information describing how to create a Windows Itanium toolchain.
9+
10+
Windows Itanium allows you to deploy Itanium C++ ABI applications on top of the MS VS CRT.
11+
This environment can use the Windows SDK headers directly and does not required additional
12+
headers or additional runtime machinery (such as is used by mingw).
13+
14+
Windows Itanium Stack:
15+
16+
* Uses the Itanium C++ abi.
17+
* libc++.
18+
* libc++-abi.
19+
* libunwind.
20+
* The MS VS CRT.
21+
* Is compatible with MS Windows SDK include headers.
22+
* COFF/PE file format.
23+
* LLD
24+
25+
Note: compiler-rt is not used. This functionality is supplied by the MS VCRT.
26+
27+
Prerequisites
28+
=============
29+
30+
* The MS SDK is installed as part of MS Visual Studio.
31+
* Clang with support for the windows-itanium triple.
32+
* COFF LLD with support for the -autoimport switch.
33+
34+
Known issues:
35+
=============
36+
37+
SJLJ exceptions, "-fsjlj-exceptions", are the only currently supported model.
38+
39+
link.exe (the MS linker) is unsuitable as it doesn't support auto-importing which
40+
is currently required to link correctly. However, if that limitation is removed
41+
then there are no other known issues with using link.exe.
42+
43+
Currently, there is a lack of a usable Windows compiler driver for Windows Itanium.
44+
A reasonable work-around is to build clang with a windows-msvc default target and
45+
then override the triple with e.g. "-Xclang -triple -Xclang x86_64-unknown-windows-itanium".
46+
The linker can be specified with: "-fuse-ld=lld".
47+
48+
In the Itanium C++ ABI the first member of an object is a pointer to the vtable
49+
for its class. The vtable is often emitted into the object file with the key function
50+
and must be imported for classes marked dllimport. The pointers must be globally
51+
unique. Unfortunately, the COFF/PE file format does not provide a mechanism to
52+
store a runtime address from another DLL into this pointer (although runtime
53+
addresses are patched into the IAT). Therefore, the compiler must emit some code,
54+
that runs after IAT patching but before anything that might use the vtable pointers,
55+
and sets the vtable pointer to the address from the IAT. For the special case of
56+
the references to vtables for __cxxabiv1::__class_type_info from typeinto objects
57+
there is no declaration available to the compiler so this can't be done. To allow
58+
programs to link we currently rely on the -auto-import switch in LLD to auto-import
59+
references to __cxxabiv1::__class_type_info pointers (see: https://reviews.llvm.org/D43184
60+
for a related discussion). This allows for linking; but, code that actually uses
61+
such fields will not work as they these will not be fixed up at runtime. See
62+
_pei386_runtime_relocator which handles the runtime component of the autoimporting
63+
scheme used for mingw and comments in https://reviews.llvm.org/D43184 and
64+
https://reviews.llvm.org/D89518 for more.
65+
66+
Assembling a Toolchain:
67+
=======================
68+
69+
The procedure is:
70+
71+
# Build an LLVM toolchain with support for Windows Itanium.
72+
# Use the toolchain from step 1. to build libc++, libc++abi, and libunwind.
73+
74+
It is also possible to cross-compile from Linux.
75+
76+
One method of building the libraries in step 2. is to build them "stand-alone".
77+
A stand-alone build doesn't involve the rest of the LLVM tree. The steps are:
78+
79+
* ``cd build-dir``
80+
* ``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>``
81+
* ``<make program e.g. ninja>``
82+
* ``<make program> install``
83+
84+
More information on standalone builds can be found in the build documentation for
85+
the respective libraries. The next section discuss the salient options and modifications
86+
required for building and installing the libraries using standalone builds. This assumes
87+
that we are building libunwind and ibc++ as DLLs and statically linking libc++abi into
88+
libc++. Other build configurations are possible, but they are not discussed here.
89+
90+
Common CMake configuration options:
91+
-----------------------------------
92+
93+
* ``-D_LIBCPP_ABI_FORCE_ITANIUM'``
94+
95+
Tell the libc++ headers that the Itanium C++ ABI is being used.
96+
97+
* ``-DCMAKE_C_FLAGS="-lmsvcrt -llegacy_stdio_definitions -D_NO_CRT_STDIO_INLINE"``
98+
99+
Supply CRT definitions including stdio definitions that have been removed from the MS VS CRT.
100+
We don't want the stdio functions decalred inline as they will casuse multiple defintiion
101+
errors when the same symbols are pulled in from legacy_stdio_definitions.ib.
102+
103+
* ``-DCMAKE_INSTALL_PREFIX=<install path>``
104+
105+
Where to install the library and headers.
106+
107+
Building libunwind:
108+
-------------------
109+
110+
* ``-DLIBUNWIND_ENABLE_SHARED=ON``
111+
* ``-DLIBUNWIND_ENABLE_STATIC=OFF``
112+
113+
libunwind can be built as a DLL. It is not dependent on other projects.
114+
115+
* ``-DLIBUNWIND_USE_COMPILER_RT=OFF``
116+
117+
We use the MS runtime.
118+
119+
The CMake files will need to be edited to prevent them adding GNU specific libraries to the link line.
120+
121+
Building libc++abi:
122+
------------------
123+
124+
* ``-DLIBCXXABI_ENABLE_SHARED=OFF``
125+
* ``-DLIBCXXABI_ENABLE_STATIC=ON``
126+
* ``-DLIBCXX_ENABLE_SHARED=ON'``
127+
* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON``
128+
129+
To break the symbol dependency between libc++abi and libc++ we
130+
build libc++abi as a static library and then statically link it
131+
into the libc++ DLL. This necessitates setting the CMake file
132+
to ensure that the visibility macros (which expand to dllexport/import)
133+
are expanded as they will be needed when creating the final libc++
134+
DLL later, see: https://reviews.llvm.org/D90021.
135+
136+
* ``-DLIBCXXABI_LIBCXX_INCLUDES=<path to libcxx>/include``
137+
138+
Where to find the libc++ headers
139+
140+
Building libc++:
141+
----------------
142+
143+
* ``-DLIBCXX_ENABLE_SHARED=ON``
144+
* ``-DLIBCXX_ENABLE_STATIC=OFF``
145+
146+
We build libc++ as a DLL and statically link libc++abi into it.
147+
148+
* ``-DLIBCXX_INSTALL_HEADERS=ON``
149+
150+
Install the headers.
151+
152+
* ``-DLIBCXX_USE_COMPILER_RT=OFF``
153+
154+
We use the MS runtime.
155+
156+
* ``-DLIBCXX_HAS_WIN32_THREAD_API=ON``
157+
158+
Windows Itanium does not offer a POSIX-like layer over WIN32.
159+
160+
* ``-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON``
161+
* ``-DLIBCXX_CXX_ABI=libcxxabi``
162+
* ``-DLIBCXX_CXX_ABI_INCLUDE_PATHS=<libcxxabi src path>/include``
163+
* ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=<libcxxabi build path>/lib``
164+
165+
Use the static libc++abi library built earlier.
166+
167+
* ``-DLIBCXX_NO_VCRUNTIME=ON``
168+
169+
Remove any dependency on the VC runtime - we need libc++abi to supply the C++ runtime.
170+
171+
* ``-DCMAKE_C_FLAGS=<path to installed unwind.lib>``
172+
173+
As we are statically linking against libcxxabi we need to link
174+
against the unwind import library to resolve unwind references
175+
from the libcxxabi objects.
176+
177+
* ``-DCMAKE_C_FLAGS+=' -UCLOCK_REALTIME'``
178+
179+
Prevent the inclusion of sys/time that MS doesn't provide.
180+
181+
Notes:
182+
------
183+
184+
An example build recipe is available here: https://reviews.llvm.org/D88124

llvm/docs/UserGuides.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ intermediate LLVM representation.
3333
GoldPlugin
3434
HowToBuildOnARM
3535
HowToBuildWithPGO
36+
HowToBuildWindowsItaniumPrograms
3637
HowToCrossCompileBuiltinsOnArm
3738
HowToCrossCompileLLVM
3839
HowToUpdateDebugInfo
@@ -198,6 +199,9 @@ Additional Topics
198199
Gives the steps necessary when adding a new constrained math intrinsic
199200
to LLVM.
200201

202+
:doc:`HowToBuildWindowsItaniumPrograms`
203+
Notes on assembling a Windows Itanium enviroment.
204+
201205
:doc:`HowToCrossCompileBuiltinsOnArm`
202206
Notes on cross-building and testing the compiler-rt builtins for Arm.
203207

0 commit comments

Comments
 (0)