Update docs

Author: Meinersbur

flang-rt/README.md

@@ -6,15 +6,15 @@
 
 -->
 
-# Fortran Runtime (flang-rt)
+# Fortran Runtime (Flang-RT)
 
-Flang-rt is the runtime library for code emitted by the Flang compiler
+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
+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
@@ -34,31 +34,31 @@ 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
+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>/llvm    \
-  -DNinja                               \
-  -DLLVM_ENABLE_PROJECTS=flang          \
-  -DLLVM_ENABLE_RUNTIMES=flang-rt \
+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
+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"               \
+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" \
   ...
 ```
@@ -85,16 +85,16 @@ 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
+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
-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 might look like the following:
+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 might look like the following:
 
 ```bash
-cmake -S <path-to-llvm-project>/runtimes                     \
+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 \
@@ -107,16 +107,16 @@ 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
+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
+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.
 
 A more complete build configuration could be the following:
 
 ```bash
-cmake -S <path-to-llvm-project>/runtimes                                      \
+cmake -S <path-to-llvm-project-source>/runtimes                               \
   -GNinja                                                                     \
   -DCMAKE_BUILD_TYPE=Release                                                  \
   -DCMAKE_INSTALL_PREFIX="${HOME}/local"                                      \
@@ -134,7 +134,7 @@ cmake -S <path-to-llvm-project>/runtimes                                      \
 
 ## Configuration Option Reference
 
-Flang-rt has the followign configuration options. This is in
+Flang-RT has the followign configuration options. This is in
 addition to the build options the LLVM_ENABLE_RUNTIMES mechanism and
 CMake itself provide.
 
@@ -153,11 +153,11 @@ CMake itself provide.
 
  * `FLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT` (values: `"CUDA"`,`"OpenMP"`, `""` default: `""`)
 
-   When set to `CUDA`, builds flang-rt with experimental support for GPU
+   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
+   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`.
 
@@ -170,7 +170,7 @@ CMake itself provide.
    (no `CMAKE_CUDA_COMPILER`).
 
 
-### CUDA Support
+### Exprimental CUDA Support
 
 With `-DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA`, the following
 additional configuration options become available.
@@ -186,13 +186,13 @@ additional configuration options become available.
    default.
 
 
-### OpenMP Offload Support
+### Exprimental 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 supporting.
+   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.

flang-rt/lib/CufRuntime/CMakeLists.txt

@@ -6,9 +6,6 @@
 #
 #===------------------------------------------------------------------------===#
 
-# Phony build target that does not include the CUDA version.
-add_custom_target(CufRuntime)
-
 # libCufRuntime depends on a certain version of CUDA. To be able to have
 # multiple build of this library with different CUDA version, the version is
 # added to the library name.
@@ -23,7 +20,6 @@ add_flangrt_library(${CUFRT_LIBNAME}
   memory.cpp
   registration.cpp
 )
-add_dependencies(CufRuntime ${CUFRT_LIBNAME})
 target_include_directories(${CUFRT_LIBNAME} PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
 
 if (BUILD_SHARED_LIBS)
@@ -37,3 +33,8 @@ target_link_libraries(${CUFRT_LIBNAME}
   flang_rt
   ${CUDA_RT_TARGET}
 )
+
+# Phony build target that does not include the CUDA version.
+add_custom_target(CufRuntime)
+add_dependencies(CufRuntime ${CUFRT_LIBNAME})
+

flang/docs/GettingStarted.md

@@ -197,7 +197,7 @@ Flang runtime can be built for accelerators in experimental mode, i.e.
 complete enabling is WIP.  CUDA and OpenMP target offload builds
 are currently supported.
 
-#### Building out-of-tree (Runtime-only build)
+#### Building out-of-tree (runtime-only build)
 
 ##### CUDA build
 Clang with NVPTX backend and NVCC compilers are supported.
@@ -209,15 +209,15 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
-  -DLLVM_ENABLE_RUNTIMES=flang_rt \
+  -DLLVM_ENABLE_RUNTIMES=flang-rt \
   -DFLANG_RT_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++ \
   ../runtimes/
-make -j`nprocs` flang_rt
+make flang-rt
 ```
 
 Note that the used version of `clang` must [support](https://releases.llvm.org/16.0.0/tools/clang/docs/ReleaseNotes.html#cuda-support)
@@ -232,7 +232,7 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
-  -DLLVM_ENABLE_RUNTIMES=flang_rt \
+  -DLLVM_ENABLE_RUNTIMES=flang-rt \
   -DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=clang \
@@ -241,7 +241,7 @@ cmake \
   -DCMAKE_CUDA_HOST_COMPILER=clang++ \
   ../runtimes/
 
-make -j`nprocs` flang_rt
+make flang-rt
 ```
 
 Note that `nvcc` might limit support to certain
@@ -260,7 +260,7 @@ build config:
 
 For example:
 ```bash
-  -DLLVM_ENABLE_RUNTIMES=flang_rt \
+  -DLLVM_ENABLE_RUNTIMES=flang-rt \
   -DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=clang \
@@ -272,7 +272,7 @@ For example:
 
 Or:
 ```bash
-  -DLLVM_ENABLE_RUNTIMES=flang_rt \
+  -DLLVM_ENABLE_RUNTIMES=flang-rt \
   -DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT=CUDA \
   -DCMAKE_CUDA_ARCHITECTURES=80 \
   -DCMAKE_C_COMPILER=gcc \
@@ -282,8 +282,11 @@ Or:
   ../llvm
 ```
 
-Normal `make -j`nprocs` check-flang` will work with such CMake configuration.
-Consider a lower value instead of `nprocs` appropriate to the available RAM.
+Normal `make check-flang` will work with such CMake configuration.
+Consider building in parallel using the `-j<jobs>` flag, where `<jobs>` is a
+number low enough for all build jobs to fit into the available RAM. Using
+the number of harware threads (`nprocs`) is likely too much for most
+commodity computers.
 
 ##### OpenMP target offload build
 Only Clang compiler is currently supported.
@@ -295,14 +298,14 @@ mkdir build_flang_runtime
 cd build_flang_runtime
 
 cmake \
-  -DLLVM_ENABLE_RUNTIMES=flang_rt \
+  -DLLVM_ENABLE_RUNTIMES=flang-rt \
   -DFLANG_RT_EXPERIMENTAL_OFFLOAD_SUPPORT="OpenMP" \
   -DCMAKE_C_COMPILER=clang \
   -DCMAKE_CXX_COMPILER=clang++ \
-  -DFLANG_RT_DEVICE_ARCHITECTURES="all" \
+  -DFLANG_RT_DEVICE_ARCHITECTURES=all \
   ../runtimes/
 
-make -j`nprocs` flang_rt
+make flang-rt
 ```
 
 The result of the build is a "device-only" library, i.e. the host