Add documentation

Meinersbur · Meinersbur · commit f6d9f371a968 · 2024-10-07T15:55:34.000+02:00
diff --git a/FortranRuntime/README.md b/FortranRuntime/README.md
@@ -1,20 +1,142 @@
+<!--===- 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
 
 Fortran Runtime is the runtime library for code emitted by the Flang
 compiler (https://flang.llvm.org).
 
+
 ## Getting Started
 
-### Bootstrap Build
+There are two build modes for the FortranRuntime. 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
 
-```sh
-cmake -S <path-to-llvm-project>/llvm -DLLVM_ENABLE_PROJECTS=flang -DLLVM_ENABLE_RUNTIMES=FortranRuntime
+Requirements:
+  * [Same as LLVM](https://llvm.org/docs/GettingStarted.html#requirements).
+  * While for LLVM C++14 suffices, Flang and FortranRuntime require a C++17-capable C++ compiler.
+
+
+### Bootstrap/In-Tree Build
+
+The bootstrap build will first build Clang and Flang, then use these compilers to compile the FortranRuntime.
+CMake will create a secondary build tree in configured with 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, the FortranRuntime is found by Flang from either the build- or install-prefix. To enable, add `FortranRuntime` to `LLVM_ENABLE_RUNTIMES`:
+
+```bash
+cmake -S <path-to-llvm-project>/llvm    \
+  -DNinja                               \
+  -DLLVM_ENABLE_PROJECTS=flang          \
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
+  ...
 ```
 
-### Runtime-only build
+It is recommended to enable building OpenMP alongside Flang and FortranRuntime 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).
 
-```sh
-cmake -S <path-to-llvm-project>/runtimes -DLLVM_ENABLE_RUNTIMES=FortranRuntime -DCMAKE_Fortran_COMPILER=<path-to-llvm-builddir-or-installprefix>/bin/flang-new
+```bash
+cmake -S <path-to-llvm-project>/llvm                  \
+  -DNinja                                             \
+  -DCMAKE_BUILD_TYPE=Release                          \
+  -DLLVM_ENABLE_PROJECTS="flang;openmp"               \
+  -DLLVM_ENABLE_RUNTIMES="compiler-rt;FortranRuntime" \
+  ...
 ```
 
+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-new --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 via
+
+```shell
+$ ninja FortranRuntime
+$ ninja check-FortranRuntime
+$ ninja install-FortranRuntime
+```
+
+
+### Runtime-only/Out-of-Tree Build
+
+Instead of building Clang and Flang from scratch, the Runtime-only 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-new` built from the same Git commit as FortranRuntime 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 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.
+A simple build configuration maight look like the following:
+
+```bash
+cmake -S <path-to-llvm-project>/runtimes                         \
+  -GNinja                                                        \
+  -DLLVM_BINARY_DIR=<path-to-llvm-builddir>                      \
+  -DCMAKE_Fortran_COMPILER=<path-to-llvm-builddir>/bin/flang-new \
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime                          \
+  ...
+```
+
+uilding the FortranRuntime for cross-compilation triple, the target triple can be selected using `LLVM_DEFAULT_TARGET_TRIPLE` AND `LLVM_RUNTIMES_TARGET`. Of course, FortranRuntime 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.
+
+A more complete build configuration could be the following:
+
+```bash
+cmake -S <path-to-llvm-project>/runtimes                                          \
+  -GNinja                                                                         \
+  -DCMAKE_BUILD_TYPE=Release                                                      \
+  -DCMAKE_INSTALL_PREFIX="${HOME}/local"                                          \
+  -DLLVM_ENABLE_RUNTIMES="compiler-rt;FortranRuntime"                             \
+  -DCMAKE_C_COMPILER=gcc                                                          \
+  -DCMAKE_CXX_COMPILER=g++                                                        \
+  -DLLVM_BINARY_DIR=<path-to-llvm-builddir>                                       \
+  -DLLVM_DIR=<path-to-llvm-builddir>/lib/cmake/llvm                               \
+  -DClang_DIR=<path-to-llvm-builddir>/lib/cmake/clang                             \
+  -DCMAKE_Fortran_COMPILER=<path-to-llvm-builddir-or-installprefix>/bin/flang-new \
+  -DLLVM_DEFAULT_TARGET_TRIPLE=x86_64-linux-gnu                                   \
+  -DLLVM_RUNTIMES_TARGET=x86_64-linux-gnu                                         \
+  ...
+```
+
+## Configuration Option Reference
+
+The FortranRuntime has the followign configuration options. This is in addition to the build options the LLVM_ENABLE_RUNTIMES mechanism and CMake itself provide.
+
+ * `FORTRANRUNTIME_INCLUDE_TESTS` (boolean; default: `ON`)
+
+   When `OFF`, does not add any tests, unittests, and omits the `check-FortranRuntime` build target.
+
+ * `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](Real16MathSupport.md).
+
+ * `FORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT` (values: `"CUDA"`,`"OpenMP"`, `""` default: `""`)
+
+   When set to `CUDA`, builds a FortranRuntime with 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 a FortranRuntime with support for GPU accelerators using OpenMP offloading. Only Clang is supported for `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`.
+
+ * `FORTRANRUNTIME_ENABLE_CUF` (bool, default: `OFF`)
+
+   Compiles the `libCufRuntime_cuda_<CUDA-version>.a/.so` library. This is independent of `FORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA` and only requires a [CUDA Toolkit installation](https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html) found (not `CMAKE_CUDA_COMPILER`).
+
+
+### CUDA Support
+
+With `-DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA`, the following additional configuration options become available.
+
+ * `FORTRANRUNTIME_LIBCUDACXX_PATH` (path, default: `""`)
+
+   Path to libcu++ package installation.
+
+ * `FORTRANRUNTIME_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.
+
+
+### OpenMP Offload Support
+
+With `-DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=OpenMP`, the following additional configuration options become available.
+
+ * `FORTRANRUNTIME_DEVICE_ARCHITECTURES` (default: `"all"`)
 
+   A list of device architectures that the FortranRuntime is supporting. If `"all"` uses a pre-defined list of architectures. Same purpose as `LIBOMPTARGET_DEVICE_ARCHITECTURES` from liboffload.
diff --git a/flang/docs/GettingStarted.md b/flang/docs/GettingStarted.md
@@ -30,10 +30,10 @@ https://llvm.org/docs/GettingStarted.html.
 All of the examples below use GCC as the C/C++ compilers and ninja as the build
 tool.
 
-### Building flang in tree
+### Building flang in tree (bootstrap build)
 Building flang in tree means building flang along with all of the projects on
-which it depends.  These projects include mlir, clang, flang, openmp, and
-compiler-rt.  Note that compiler-rt is only needed to access libraries that
+which it depends.  These projects include mlir, clang, flang, openmp,
+compiler-rt, and FortranRuntime.  Note that compiler-rt is only needed to access libraries that
 support 16 bit floating point numbers.  It's not needed to run the automated
 tests.  You can use several different C++ compilers for most of the build,
 includig GNU and clang.  But building compiler-rt requres using the clang
@@ -82,7 +82,7 @@ cmake \
   -DLLVM_TARGETS_TO_BUILD=host \
   -DLLVM_LIT_ARGS=-v \
   -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \
-  -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
+  -DLLVM_ENABLE_RUNTIMES="compiler-rt;FortranRuntime" \
   ../llvm-project/llvm
 
 ninja
@@ -209,13 +209,14 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
   -DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=clang \
   -DCMAKE_CXX_COMPILER=clang++ \
   -DCMAKE_CUDA_COMPILER=clang \
   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
-  ../runtime/
+  ../runtimes/
 make -j FortranRuntime
 ```
 
@@ -231,13 +232,14 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
   -DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=clang \
   -DCMAKE_CXX_COMPILER=clang++ \
   -DCMAKE_CUDA_COMPILER=nvcc \
   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
-  ../runtime/
+  ../runtimes/
 
 make -j FortranRuntime
 ```
@@ -251,13 +253,14 @@ code.  Note that the packaging of the libraries is different
 between [Clang](https://clang.llvm.org/docs/OffloadingDesign.html#linking-target-device-code) and NVCC, so the library must be linked using
 compatible compiler drivers.
 
-#### Building in-tree
+#### Building in-tree (bootstrap build)
 One may build Flang runtime library along with building Flang itself
 by providing these additional CMake variables on top of the Flang in-tree
 build config:
 
 For example:
 ```bash
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
   -DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=clang \
@@ -268,6 +271,7 @@ For example:
 
 Or:
 ```bash
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
   -DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=gcc \
@@ -288,11 +292,12 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
+  -DLLVM_ENABLE_RUNTIMES=FortranRuntime \
   -DFORTRANRUNTIME_EXPERIMENTAL_OFFLOAD_SUPPORT="OpenMP" \
   -DCMAKE_C_COMPILER=clang \
   -DCMAKE_CXX_COMPILER=clang++ \
   -DFORTRANRUNTIME_DEVICE_ARCHITECTURES="all" \
-  ../runtime/
+  ../runtimes/
 
 make -j FortranRuntime
 ```
diff --git a/llvm/runtimes/CMakeLists.txt b/llvm/runtimes/CMakeLists.txt
@@ -281,6 +281,7 @@ function(runtime_default_target)
                            PASSTHROUGH_PREFIXES LLVM_ENABLE_RUNTIMES
                                                 LLVM_USE_LINKER
                                                 CUDA # For runtimes that may look for the CUDA SDK (libc, offload)
+                                                FLANG_RUNTIME # Shared between Flang and FortranRuntime
                                                 ${ARG_PREFIXES}
                            EXTRA_TARGETS ${extra_targets}
                                          ${test_targets}
