llvm-project/flang-rt

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 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.

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:

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).

cmake -S <path-to-llvm-project-source>/llvm     \
  -GNinja                                       \
  -DCMAKE_BUILD_TYPE=Release                    \
  -DLLVM_ENABLE_PROJECTS="clang;flang"   \
  -DLLVM_ENABLE_RUNTIMES="compiler-rt;flang-rt;openmp" \
  ...

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

$ 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:

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

$ 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.

• FLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT (values: "CUDA", "" 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.

• 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 (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.

GPU Offloading Support

Flang-RT can be built for GPU targets (AMDGPU, NVPTX) using the LLVM runtimes build infrastructure. The easiest way to configure a build for GPU offloading is via the CMake cache file at offload/cmake/caches/FlangOffload.cmake.