[llvm-branch-commits] [clang] [flang] [lld] [llvm] [Flang] LLVM_ENABLE_RUNTIMES=flang-rt (PR #110217)

[via llvm-branch-commits]

================
@@ -0,0 +1,198 @@
+<!--===- 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).
+
+
+### Bootstrap/In-Tree Build
+
+The bootstrap build will first build Clang and Flang, then use these compilers
+to compile flang-rt. 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, 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>/llvm    \
+  -DNinja                               \
+  -DLLVM_ENABLE_PROJECTS=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>/llvm                  \
+  -DNinja                                             \
+  -DCMAKE_BUILD_TYPE=Release                          \
+  -DLLVM_ENABLE_PROJECTS="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-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(s) via
+
+```shell
+$ ninja flang-rt
+$ ninja check-flang-rt
+$ ninja install
+```
+
+
+### 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
+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 be able to find LLVM development tools
----------------
jeanPerier wrote:

```suggestion
In addition to the compiler, the build must be able to find LLVM development tools
```

https://github.com/llvm/llvm-project/pull/110217