|
| 1 | +<!--===- docs/GettingStarted.md |
| 2 | + |
| 3 | + Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| 4 | + See https://llvm.org/LICENSE.txt for license information. |
| 5 | + SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| 6 | + |
| 7 | +--> |
| 8 | + |
| 9 | +# Flang-rt Runtime Library |
| 10 | + |
| 11 | +```eval_rst |
| 12 | +.. contents:: |
| 13 | + :local: |
| 14 | +``` |
| 15 | +## What is Flang-rt |
| 16 | +Flang-rt is the runtime library project for Flang. The Flang driver requires |
| 17 | +the Fortran_main and Flang-rt libraries at runtime in order to generate |
| 18 | +user executables. Building this Flang-rt project will build both Fortran_main |
| 19 | +and the Flang-rt library, which is comprised of the FortranRuntime and |
| 20 | +FortranDecimalRT libraries. |
| 21 | + |
| 22 | +### Fortran_main |
| 23 | +Fortran_main is left out of the Flang-rt library because it is required to |
| 24 | +always be static unlike the link type of the Flang-rt library which can be |
| 25 | +configured. Fortran_main implements the main entry point into Fortran's |
| 26 | +`PROGRAM` in Flang by being the bridge between object files generated by Flang |
| 27 | +and the C runtime that takes care of program set-up at system-level. For |
| 28 | +every Fortran `PROGRAM`, Flang generates the `_QQmain` function. |
| 29 | +Fortran_main implements the C `main` function that simply calls |
| 30 | +`_QQmain`. |
| 31 | + |
| 32 | +### FortranDecimalRT |
| 33 | +In order to decouple the common dependency between compiler and runtime, |
| 34 | +[FortranDecimal's sources](../../flang/lib/Decimal/CMakeLists.txt) are built |
| 35 | +separately for the compiler and the runtime. When the library is built for |
| 36 | +Flang-rt, the name FortranDecimalRT is used to avoid naming conflicts and |
| 37 | +confusion. |
| 38 | + |
| 39 | +### FortranRuntime |
| 40 | +This is the core runtime library in Flang-rt. The sources for this library |
| 41 | +currently still exist in the |
| 42 | +[Flang source directory](../../flang/runtime/CMakeLists.txt). We hope to |
| 43 | +migrate the sources to the Flang-rt directory in the future in order to further |
| 44 | +decouple the runtime from the Flang compiler. |
| 45 | + |
| 46 | +## Building Flang-rt |
| 47 | +Like other LLVM runtimes, Flang-rt can be built by targetting the |
| 48 | +[runtimes LLVM target](../../runtimes/CMakelists.txt). It can also be built |
| 49 | +when targetting the [llvm target](../../llvm/CMakeLists.txt) as an enabled |
| 50 | +runtime. Flang-rt will implicitly be added as an enabled runtime when Flang |
| 51 | +is an enabled project built by llvm. Flang-rt does not support standalone |
| 52 | +builds. |
| 53 | + |
| 54 | +In the future, we may be interested in supporting in optionally building |
| 55 | +Flang-rt when doing a Flang standalone build. |
| 56 | + |
| 57 | +### Building with the llvm target |
| 58 | +Assuming you are building Flang-rt to use with Flang, see |
| 59 | +[Flang's Getting Started guide](../../flang/docs/GettingStarted.md) for more |
| 60 | +information. To build Flang-rt when building the Flang compiler, once you have |
| 61 | +the llvm-project source ready, make a clean build directory. Let root be the |
| 62 | +root directory that you cloned llvm-project into. |
| 63 | +```bash |
| 64 | +cd root |
| 65 | +rm -rf build |
| 66 | +mkdir build |
| 67 | +cd build |
| 68 | +``` |
| 69 | +Now invoke the cmake configuration command for llvm that would build Flang with |
| 70 | +Flang-rt. |
| 71 | +```bash |
| 72 | +cmake \ |
| 73 | + -G Ninja \ |
| 74 | + -DLLVM_ENABLE_RUNTIMES="compiler-rt;flang-rt" \ |
| 75 | + -DCMAKE_CXX_STANDARD=17 \ |
| 76 | + -DLLVM_INSTALL_UTILS=On \ |
| 77 | + # New Flang-rt flags for enabled link types |
| 78 | + -DFLANG_RT_ENABLE_STATIC=On \ |
| 79 | + -DFLANG_RT_ENABLE_SHARED=On \ |
| 80 | + # We need to enable GTest if we want to run Flang-rt's testsuites |
| 81 | + -DLLVM_INSTALL_GTEST=On \ |
| 82 | + -DFLANG_ENABLE_WERROR=On \ |
| 83 | + -DLLVM_LIT_ARGS=-v \ |
| 84 | + -DCMAKE_BUILD_TYPE=Release \ |
| 85 | + -DLLVM_ENABLE_PROJECTS="clang;flang;lld;mlir;openmp" \ |
| 86 | + ../llvm-project/llvm |
| 87 | +``` |
| 88 | +Flang requires other llvm projects (see LLVM_ENABLE_PROJECTS and the [Flang |
| 89 | +Getting Started Guide](../../flang/docs/GettingStarted.md) for more specifics |
| 90 | +on building Flang. |
| 91 | + |
| 92 | +By targetting the LLVM project, we are letting LLVM infrastructure handle |
| 93 | +invoking the runtimes target that will build Flang-rt. This includes finding |
| 94 | +the cmake packages for Clang, LLVM, Flang and MLIR that Flang-rt depends on. |
| 95 | + |
| 96 | +### Building with the runtimes target |
| 97 | +If you already have a pre-built/installed version of LLVM, Flang, Clang and |
| 98 | +MLIR, and would like to build Flang-rt without rebuilding the sources for these |
| 99 | +other projects. You can simply target the runtimes project directly and passing |
| 100 | +the paths to the directories of these files. If you built LLVM as we did above |
| 101 | +with default build directories, your runtimes invocation should look something |
| 102 | +like: |
| 103 | +```bash |
| 104 | +cd build |
| 105 | +BUILDDIR=`pwd` |
| 106 | + |
| 107 | +cmake \ |
| 108 | + -G Ninja \ |
| 109 | + -DCMAKE_CXX_STANDARD=17 \ |
| 110 | + # New Flang-rt flags for enabled link types |
| 111 | + -DFLANG_RT_ENABLE_SHARED=On \ |
| 112 | + -DFLANG_RT_ENABLE_STATIC=On \ |
| 113 | + -DLLVM_LIT_ARGS=-v \ |
| 114 | + -DCMAKE_BUILD_TYPE=Release \ |
| 115 | + -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \ |
| 116 | + -DLLVM_TARGETS_TO_BUILD=host \ |
| 117 | + -DLLVM_EXTERNAL_LIT=$BUILD_DIR/bin/llvm-lit \ |
| 118 | + # We need to specify the paths to the cmake packages of the dependencies |
| 119 | + -DLLVM_DIR=$BUILD_DIR/lib/cmake/llvm \ |
| 120 | + -DMLIR_DIR=$BUILD_DIR/lib/cmake/mlir \ |
| 121 | + -DFLANG_DIR=$BUILD_DIR/lib/cmake/flang \ |
| 122 | + -DLLVM_ENABLE_RUNTIMES="flang-rt" \ |
| 123 | + ../llvm-project/runtimes/ |
| 124 | +``` |
| 125 | + |
| 126 | +## Library locations |
| 127 | +When building the llvm target with flang as an enabled project, the Flang-rt |
| 128 | +library will be built to `$BUILDDIR/runtimes/runtimes-bins/flang-rt/lib`. When |
| 129 | +building the runtimes target with flang-rt as an enabled runtime, the libraries |
| 130 | +will be built to `$BUILDDIR/flang-rt/lib` by default. In either configuration, |
| 131 | +the Fortran_main library will be built to `$BUILDDIR/lib` by default. |
| 132 | + |
| 133 | +## Using Flang-rt |
| 134 | +The two build paths mentioned above get implicitly added as library paths at the |
| 135 | +invocation of the driver. If Flang-rt is a shared library, you must make the |
| 136 | +dynamic linker aware of where to look. One method to do so is to set the |
| 137 | +environment variable `LD_LIBRARY_PATH` include the path to Flang-rt's directory. |
| 138 | + |
| 139 | +## Options |
| 140 | +Flang-rt introduces 2 CMake options used to configure the library's link type: |
| 141 | +``` |
| 142 | +option(FLANG_RT_ENABLE_SHARED "Build flang-rt as a shared library." OFF) |
| 143 | +option(FLANG_RT_ENABLE_STATIC "Build flang-rt as a static library." OFF) |
| 144 | +``` |
| 145 | +Both can be specified if you want to build both shared and static versions of |
| 146 | +the Flang-rt runtime. If both are specified, the static library will be named |
| 147 | +Flang-rt_static.a to avoid naming conflicts, as per the LLVM standard. |
| 148 | + |
| 149 | +## Usage Examples |
| 150 | +```bash |
| 151 | +# Example of using Flang with the shared Flang-rt runtime |
| 152 | +# First we need to explicitly tell the dynamic linker where to find Flang-rt |
| 153 | +# since it was built as shared. |
| 154 | +$ $ export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$BUILDDIR/runtimes/runtimes-bins/flang-rt/lib" |
| 155 | +$ flang-new -ffree-form hello.f95 -o hello |
| 156 | +``` |
0 commit comments