[Openmp-commits] [openmp] [OpenMP][docs] Revise building manual (PR #176175)

[Michael Kruse via Openmp-commits]

================
@@ -0,0 +1,361 @@
+# Building the OpenMP Libraries
+
+LLVM OpenMP uses a CMake-based build system. For generic information on the LLVM
+build system see
+[LLVM's Getting Started](https://llvm.org/docs/GettingStarted.html) and
+[Advanced Build](https://llvm.org//docs/AdvancedBuilds.html) pages.
+
+
+## Requirements
+
+LLVM OpenMP shares the same requirements as LLVM itself. See
+[LLVM's Requirements](https://llvm.org/docs/GettingStarted.html#requirements)
+for those requirements.
+
+
+### Requirements for Building with Nvidia GPU support
+
+The CUDA SDK is required on the machine that will build and execute the
+offloading application. Normally this is only required at runtime by dynamically
+opening the CUDA driver API. This can be disabled in the build by omitting
+`cuda` from the [`LIBOMPTARGET_DLOPEN_PLUGINS`](LIBOMPTARGET_DLOPEN_PLUGINS)
+list which is present by default. With this setting we will instead find the
+CUDA library at LLVM build time and link against it directly.
+
+
+### Requirements for Building with AMD GPU support
+
+The OpenMP AMDGPU offloading support depends on the ROCm math libraries and the
+HSA ROCr / ROCt runtimes. These are normally provided by a standard ROCm
+installation, but can be built and used independently if desired. Building the
+libraries does not depend on these libraries by default by dynamically loading
+the HSA runtime at program execution. As in the CUDA case, this can be change by
+omitting `amdgpu` from the
+[`LIBOMPTARGET_DLOPEN_PLUGINS`](LIBOMPTARGET_DLOPEN_PLUGINS) list.
+
+
+## Building on Linux
+
+### Bootstrapping Build
+
+An LLVM *bootstrapping build* compiles LLVM and Clang first, then uses this just-built clang to build the runtimes such as OpenMP.
+
+```sh
+git clone https://github.com/llvm/llvm-project.git
+cd llvm-project
+mkdir build
+cd build
+cmake ../llvm -G Ninja           \
+    -DCMAKE_BUILD_TYPE=Release    \
+    -DCMAKE_INSTALL_PREFIX=<PATH> \
+    -DLLVM_ENABLE_PROJECTS=clang  \
+    -DLLVM_ENABLE_RUNTIMES=openmp
+ninja              # Build
+ninja check-openmp # Run regression and unit tests
+ninja install      # Installs files to <PATH>/bin, <PATH>/lib, etc
+```
+
+Without any further options, this builds the OpenMP libraries for the host
+triple (e.g. when the host is `x86_64-linux-gnu`, this builds `libomp.so`
+also for `x86_64-linux-gnu`). For building the libraries for additional,
+cross-compilation target, they can be passed using `LLVM_RUNTIME_TARGETS`.
+Internally, a new CMake build directory for each target triple will be created.
+Configuration parameters with `OPENMP_` and `LIBOMP_` prefix are automatically
+forwarded to all runtime build directories (but not others such as `LIBOMPT_` or
+`LIBOMPTARGET_` prefixes). Other configuration parameters that should apply to
+the runtimes can be passed via `RUNTIMES_CMAKE_ARGS`. For a parameter to be
+passed to the build of only one target triple, set the parameter
+`RUNTIMES_<triple>_<runtimes-parameter>`. For example:
+
+```sh
+cmake ../llvm -G Ninja                                           \
+    -DCMAKE_BUILD_TYPE=Release                                   \
+    -DCMAKE_INSTALL_PREFIX=<PATH>                                \
+    -DLLVM_ENABLE_PROJECTS=clang                                 \
+    -DLLVM_ENABLE_RUNTIMES=openmp                                \
+    -DLLVM_RUNTIME_TARGETS="default;aarch64-linux-gnu"           \
+    -DOPENMP_ENABLE_OMPT_TOOLS=ON                                \
+    -DRUNTIMES_CMAKE_ARGS="-DLIBOMPTEST_INSTALL_COMPONENTS=ON"   \
+    -DRUNTIMES_arch64-linux-gnu_CMAKE_CXX_FLAGS="-march=armv8-a"
+```
+
+If [`CMAKE_INSTALL_PREFIX`][CMAKE_INSTALL_PREFIX] is omitted, CMake defaults to
+`/usr/local` to install the libraries globally. This is not recommended since it
+may be in interfere with the system's OpenMP installation, such as `omp.h` from
+gcc.
+
+
+(default_runtimes_build)=
+### Runtimes Default/Standalone Build
+
+An LLVM *default runtimes build* (sometimes also *standalone runtimes build*)
+uses an pre-existing LLVM and Clang builds to directly compile the OpenMP
+libraries.
+
+```sh
+git clone https://github.com/llvm/llvm-project.git
+cd llvm-project
+mkdir build-runtimes
+cd build-runtimes
+cmake ../runtimes -G Ninja         \
+    -DCMAKE_BUILD_TYPE=Release     \
+    -DCMAKE_INSTALL_PREFIX=<PATH>  \
+    -DLLVM_BINARY_DIR=../build \
+    -DLLVM_ENABLE_RUNTIMES=openmp
+ninja              # Build
+ninja check-openmp # Run regression and unit tests
+ninja install      # Installs files to <PATH>/bin, <PATH>/lib, etc
+```
+
+where `../build` is the path to a completed LLVM and Clang build. It is expected
+to have been built from the same Git commit as OpenMP. It will, however, use the
+compiler detected by CMake, usually gcc. To also make it use Clang, add
+`-DCMAKE_C_COMPILER=../build/bin/clang -DCMAKE_C_COMPILER=../build/bin/clang++`.
+
+
+(build_offload_capable_compiler)=
+### Building with Offload Support
+
+Enabling support for offloading (i.e. `#pragma omp target`) additionally
+requires the offload runtime. Host offloading (i.e. using the CPU itself as
+an offloading target) should work out of the box, but each GPU architecture
+requires its own runtime. Currently supported GPU architectures are
+`amdgcn-amd-amdhsa` and `nvptx-nvidia-cuda`. A minimal build configuration
+supporting both architectures would be the following.
+
+```sh
+git clone https://github.com/llvm/llvm-project.git
+cd llvm-project
+mkdir build
+cd build
+cmake ../llvm -G Ninja                                                     \
+    -DCMAKE_BUILD_TYPE=Release                                             \
+    -DCMAKE_INSTALL_PREFIX=<PATH>                                          \
+    -DLLVM_ENABLE_PROJECTS=clang                                           \
+    -DLLVM_ENABLE_RUNTIMES="openmp;offload"                                \
----------------
Meinersbur wrote:

https://github.com/llvm/llvm-project/pull/176175#issuecomment-3755173131

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