1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<!--===- README.md
Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
See https://llvm.org/LICENSE.txt for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-->
# Fortran Runtime (Flang-RT)
Flang-RT is the runtime library for code emitted by the Flang compiler
(https://flang.llvm.org).
## Getting Started
There are two build modes for the Flang-RT. The bootstrap build, also
called the in-tree build, and the runtime-only build, also called the
out-of-tree build.
Not to be confused with the terms
[in-source and out-of-source](https://cmake.org/cmake/help/latest/manual/cmake.1.html#introduction-to-cmake-buildsystems)
builds as defined by CMake. In an in-source build, the source directory and the
build directory are identical, whereas with an out-of-source build the
build artifacts are stored somewhere else, possibly in a subdirectory of the
source directory. LLVM does not support in-source builds.
### Requirements
Requirements:
* [Same as LLVM](https://llvm.org/docs/GettingStarted.html#requirements).
### Bootstrapping Runtimes Build
The bootstrapping build will first build Clang and Flang, then use these
compilers to compile Flang-RT. CMake will create a secondary build tree
configured to use these just-built compilers. The secondary build will reuse
the same build options (Flags, Debug/Release, ...) as the primary build.
It will also ensure that once built, Flang-RT is found by Flang from either
the build- or install-prefix. To enable, add `flang-rt` to
`LLVM_ENABLE_RUNTIMES`:
```bash
cmake -S <path-to-llvm-project-source>/llvm \
-GNinja \
-DLLVM_ENABLE_PROJECTS="clang;flang" \
-DLLVM_ENABLE_RUNTIMES=flang-rt \
...
```
It is recommended to enable building OpenMP alongside Flang and Flang-RT
as well. This will build `omp_lib.mod` required to use OpenMP from Fortran.
Building Compiler-RT may also be required, particularly on platforms that do
not provide all C-ABI functionality (such as Windows).
```bash
cmake -S <path-to-llvm-project-source>/llvm \
-GNinja \
-DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_PROJECTS="clang;flang;openmp" \
-DLLVM_ENABLE_RUNTIMES="compiler-rt;flang-rt" \
...
```
By default, the enabled runtimes will only be built for the host platform
(`-DLLVM_RUNTIME_TARGETS=default`). To add additional targets to support
cross-compilation via `flang --target=<target-triple>`, add more triples to
`LLVM_RUNTIME_TARGETS`, such as
`-DLLVM_RUNTIME_TARGETS="default;aarch64-linux-gnu"`.
After configuration, build, test, and install the runtime(s) via
```shell
$ ninja flang-rt
$ ninja check-flang-rt
$ ninja install
```
### Standalone Runtimes Build
Instead of building Clang and Flang from scratch, the standalone Runtime build
uses CMake's environment introspection to find a C, C++, and Fortran compiler.
The compiler to be used can be controlled using CMake's standard mechanisms such
as `CMAKE_CXX_COMPILER`, `CMAKE_CXX_COMPILER`, and `CMAKE_Fortran_COMPILER`.
`CMAKE_Fortran_COMPILER` must be `flang` built from the same Git commit as
Flang-RT to ensure they are using the same ABI. The C and C++ compiler
can be any compiler supporting the same ABI.
In addition to the compiler, the build must be able to find LLVM development
tools such as `lit` and `FileCheck` that are not found in an LLVM's install
directory. Use `CMAKE_BINARY_DIR` to point to directory where LLVM has
been built. When building Flang as part of a bootstrapping build
(`LLVM_ENABLE_PROJECTS=flang`), Flang-RT is automatically added
unless configured with `-DFLANG_ENABLE_FLANG_RT=OFF`. Add that option to avoid
having two conflicting versions of the same library.
A simple build configuration might look like the following:
```bash
cmake -S <path-to-llvm-project-source>/runtimes \
-GNinja \
-DLLVM_BINARY_DIR=<path-to-llvm-builddir> \
-DCMAKE_Fortran_COMPILER=<path-to-llvm-builddir>/bin/flang \
-DCMAKE_Fortran_COMPILER_WORKS=yes \
-DLLVM_ENABLE_RUNTIMES=flang-rt \
...
```
The `CMAKE_Fortran_COMPILER_WORKS` parameter must be set because otherwise CMake
will test whether the Fortran compiler can compile and link programs which will
obviously fail without a runtime library available yet.
Building Flang-RT for cross-compilation triple, the target triple can
be selected using `LLVM_DEFAULT_TARGET_TRIPLE` AND `LLVM_RUNTIMES_TARGET`.
Of course, Flang-RT can be built multiple times with different build
configurations, but have to be located manually when using with the Flang
driver using the `-L` option.
After configuration, build, test, and install the runtime via
```shell
$ ninja
$ ninja check-flang-rt
$ ninja install
```
## Configuration Option Reference
Flang-RT has the followign configuration options. This is in
addition to the build options the LLVM_ENABLE_RUNTIMES mechanism and
CMake itself provide.
* `FLANG_RT_INCLUDE_TESTS` (boolean; default: `ON`)
When `OFF`, does not add any tests and unittests. The `check-flang-rt`
build target will do nothing.
* `FLANG_RUNTIME_F128_MATH_LIB` (default: `""`)
Determines the implementation of `REAL(16)` math functions. If set to
`libquadmath`, uses `quadmath.h` and `-lquadmath` typically distributed with
gcc. If empty, disables `REAL(16)` support. For any other value, introspects
the compiler for `__float128` or 128-bit `long double` support.
[More details](docs/Real16MathSupport.md).
* `FLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT` (values: `"CUDA"`,`"OpenMP"`, `""` default: `""`)
When set to `CUDA`, builds Flang-RT with experimental support for GPU
accelerators using CUDA. `CMAKE_CUDA_COMPILER` must be set if not
automatically detected by CMake. `nvcc` as well as `clang` are supported.
When set to `OpenMP`, builds Flang-RT with experimental support for
GPU accelerators using OpenMP offloading. Only Clang is supported for
`CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`.
* `FLANG_RT_INCLUDE_CUF` (bool, default: `OFF`)
Compiles the `libflang_rt.cuda_<CUDA-version>.a/.so` library. This is
independent of `FLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA` and only
requires a
[CUDA Toolkit installation](https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html)
(no `CMAKE_CUDA_COMPILER`).
### Experimental CUDA Support
With `-DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA`, the following
additional configuration options become available.
* `FLANG_RT_LIBCUDACXX_PATH` (path, default: `""`)
Path to libcu++ package installation.
* `FLANG_RT_CUDA_RUNTIME_PTX_WITHOUT_GLOBAL_VARS` (boolean, default: `OFF`)
Do not compile global variables' definitions when producing PTX library.
Default is `OFF`, meaning global variable definitions are compiled by
default.
### Experimental OpenMP Offload Support
With `-DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=OpenMP`, the following
additional configuration options become available.
* `FLANG_RT_DEVICE_ARCHITECTURES` (default: `"all"`)
A list of device architectures that Flang-RT is going to support.
If `"all"` uses a pre-defined list of architectures. Same purpose as
`LIBOMPTARGET_DEVICE_ARCHITECTURES` from liboffload.
|
