[Openmp-commits] [openmp] [OpenMP][docs] Revise building manual (PR #176175)
Eli Friedman via Openmp-commits
openmp-commits at lists.llvm.org
Thu Jan 15 16:50:42 PST 2026
================
@@ -0,0 +1,375 @@
+# 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++`.
+In any case, it will use Clang from `LLVM_BINARY_DIR` for running the regression
+tests.
+
+
+(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`. Use the aforementioned
+`RUNTIMES_<triple>_<runtimes-parameter>` form to restrict an option
+`<runtimes-parameter>` to only only one of these architectures. 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" \
+ -DLLVM_RUNTIME_TARGETS="default;amdgcn-amd-amdhsa;nvptx64-nvidia-cuda"
+ninja # Build
+ninja check-openmp check-offload # Run regression and unit tests
+ninja install # Installs files to <PATH>/bin, <PATH>/lib, etc
+```
+
+If using a [default/standalone runtimes build](default_runtimes_build), ensure
+that in addition to `LLVM_BINARY_DIR`, `CMAKE_C_COMPILER` and
+`CMAKE_CXX_COMPILER` is Clang built from the same git commit as OpenMP, and that
+`AMDGPU` and `NVPTX` is enabled in its ``LLVM_TARGETS_TO_BUILD`` configuration
+(which is by default).
+
+A more complete build which for instance supports the libc++ on the device
+requires more options. Using CMake's
+[`-C`](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-C)
+option allows to conveniently use pre-defined set from a file.
+
+```sh
+cmake ../llvm -G Ninja \
+ -C ../offload/cmake/caches/Offload.cmake \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=<PATH>
+```
+
+
+### Building on Windows
+
+Building the OpenMP libraries in Windows is not much different than on Linux,
+only accounting for some differences of the shell (`cmd.exe`; for PowerShell
+replace the end-of-line escape character `^` with a backtick `` ` ``).
+
+```bat
+ 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
+ ninja check-openmp
+ ninja install
+```
+
+Compiling OpenMP with the MSVC compiler for a
+[runtimes default build](default_runtimes_build) is possible as well:
+
+```bat
+ cmake ..\runtimes -G Ninja ^
+ -DCMAKE_BUILD_TYPE=Release ^
+ -DCMAKE_INSTALL_PREFIX=<PATH> ^
+ -DLLVM_BINARY_DIR=../build ^
+ -DLLVM_ENABLE_RUNTIMES=openmp
+```
+
+However, offloading is not supported on the Windows platform.
+
+
+### Building on MacOS
+
+On macOS machines, it is possible to build universal (or fat) libraries which
+include both i386 and x86_64 architecture objects in a single archive.
+
+```console
+$ cmake ../llvm -G Ninja \
+ -DCMAKE_C_COMPILER=clang \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' \
+ ..
+$ ninja
+```
+
+There is also an option [`LIBOMP_OSX_ARCHITECTURES`](LIBOMP_OSX_ARCHITECTURES)
+which can be set in case this is an LLVM source tree build. It will only apply
----------------
efriedma-quic wrote:
Maybe delete this paragraph? An "LLVM source tree build" isn't meaningful. (In theory you could choose to build libomp as a fat binary, and other runtime libraries as non-fat, but that seems like an edge case.)
https://github.com/llvm/llvm-project/pull/176175
More information about the Openmp-commits
mailing list