[Openmp-commits] [openmp] [OpenMP][docs] Revise building manual (PR #176175)
Michael Kruse via Openmp-commits
openmp-commits at lists.llvm.org
Thu Jan 15 07:49:34 PST 2026
https://github.com/Meinersbur updated https://github.com/llvm/llvm-project/pull/176175
>From 7acc812181519066d609b74adaced4579624757a Mon Sep 17 00:00:00 2001
From: Michael Kruse <llvm-project at meinersbur.de>
Date: Thu, 15 Jan 2026 15:22:58 +0100
Subject: [PATCH 1/3] [OpenMP][docs] Revise building instructions
---
openmp/README.rst | 396 ------------------
openmp/docs/Building.md | 361 ++++++++++++++++
openmp/docs/SupportAndFAQ.rst | 73 ----
.../llvm-openmp-theme/static/agogo.css_t | 6 +
openmp/docs/conf.py | 14 +-
openmp/docs/index.rst | 34 +-
6 files changed, 397 insertions(+), 487 deletions(-)
delete mode 100644 openmp/README.rst
create mode 100644 openmp/docs/Building.md
diff --git a/openmp/README.rst b/openmp/README.rst
deleted file mode 100644
index cc485f9a56ce0..0000000000000
--- a/openmp/README.rst
+++ /dev/null
@@ -1,396 +0,0 @@
-========================================
-How to Build the LLVM* OpenMP* Libraries
-========================================
-This repository requires `CMake <http://www.cmake.org/>`_ v2.8.0 or later. LLVM
-and Clang need a more recent version which also applies for in-tree builds. For
-more information than available in this document please see
-`LLVM's CMake documentation <https://llvm.org/docs/CMake.html>`_ and the
-`official documentation <https://cmake.org/cmake/help/v2.8.0/cmake.html>`_.
-
-.. contents::
- :local:
-
-How to Call CMake Initially, then Repeatedly
-============================================
-- When calling CMake for the first time, all needed compiler options must be
- specified on the command line. After this initial call to CMake, the compiler
- definitions must not be included for further calls to CMake. Other options
- can be specified on the command line multiple times including all definitions
- in the build options section below.
-- Example of configuring, building, reconfiguring, rebuilding:
-
- .. code-block:: console
-
- $ mkdir build
- $ cd build
- $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. # Initial configuration
- $ make
- ...
- $ make clean
- $ cmake -DCMAKE_BUILD_TYPE=Debug .. # Second configuration
- $ make
- ...
- $ rm -rf *
- $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. # Third configuration
- $ make
-
-- Notice in the example how the compiler definitions are only specified for an
- empty build directory, but other build options are used at any time.
-- The file ``CMakeCache.txt`` which is created after the first call to CMake is
- a configuration file which holds all values for the build options. These
- values can be changed using a text editor to modify ``CMakeCache.txt`` as
- opposed to using definitions on the command line.
-- To have CMake create a particular type of build generator file simply include
- the ``-G <Generator name>`` option:
-
- .. code-block:: console
-
- $ cmake -G "Unix Makefiles" ...
-
- You can see a list of generators CMake supports by executing the cmake command
- with no arguments.
-
-Instructions to Build
-=====================
-.. code-block:: console
-
- $ cd openmp_top_level/ [ this directory with libomptarget/, runtime/, etc. ]
- $ mkdir build
- $ cd build
-
- [ Unix* Libraries ]
- $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
-
- [ Windows* Libraries ]
- $ cmake -G <Generator Type> -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release ..
-
- $ make
- $ make install
-
-CMake Options
-=============
-Builds with CMake can be customized by means of options as already seen above.
-One possibility is to pass them via the command line:
-
-.. code-block:: console
-
- $ cmake -DOPTION=<value> path/to/source
-
-.. note:: The first value listed is the respective default for that option.
-
-Generic Options
----------------
-For full documentation consult the CMake manual or execute
-``cmake --help-variable VARIABLE_NAME`` to get information about a specific
-variable.
-
-**CMAKE_BUILD_TYPE** = ``Release|Debug|RelWithDebInfo``
- Build type can be ``Release``, ``Debug``, or ``RelWithDebInfo`` which chooses
- the optimization level and presence of debugging symbols.
-
-**CMAKE_C_COMPILER** = <C compiler name>
- Specify the C compiler.
-
-**CMAKE_CXX_COMPILER** = <C++ compiler name>
- Specify the C++ compiler.
-
-**CMAKE_Fortran_COMPILER** = <Fortran compiler name>
- Specify the Fortran compiler. This option is only needed when
- **LIBOMP_FORTRAN_MODULES** is ``ON`` (see below). So typically, a Fortran
- compiler is not needed during the build.
-
-**CMAKE_ASM_MASM_COMPILER** = ``ml|ml64``
- This option is only relevant for Windows*.
-
-Options for all Libraries
--------------------------
-
-**OPENMP_ENABLE_WERROR** = ``OFF|ON``
- Treat warnings as errors and fail, if a compiler warning is triggered.
-
-**OPENMP_LIBDIR_SUFFIX** = ``""``
- Extra suffix to append to the directory where libraries are to be installed.
-
-**OPENMP_TEST_C_COMPILER** = ``${CMAKE_C_COMPILER}``
- Compiler to use for testing. Defaults to the compiler that was also used for
- building.
-
-**OPENMP_TEST_CXX_COMPILER** = ``${CMAKE_CXX_COMPILER}``
- Compiler to use for testing. Defaults to the compiler that was also used for
- building.
-
-**OPENMP_TEST_Fortran_COMPILER** = ``${CMAKE_Fortran_COMPILER}``
- Compiler to use for testing. Defaults to the compiler that was also used for
- building.
-
-**OPENMP_LLVM_TOOLS_DIR** = ``/path/to/built/llvm/tools``
- Additional path to search for LLVM tools needed by tests.
-
-**OPENMP_LLVM_LIT_EXECUTABLE** = ``/path/to/llvm-lit``
- Specify full path to ``llvm-lit`` executable for running tests. The default
- is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
-
-**OPENMP_FILECHECK_EXECUTABLE** = ``/path/to/FileCheck``
- Specify full path to ``FileCheck`` executable for running tests. The default
- is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
-
-**OPENMP_NOT_EXECUTABLE** = ``/path/to/not``
- Specify full path to ``not`` executable for running tests. The default
- is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
-
-Options for ``libomp``
-----------------------
-
-**LIBOMP_ARCH** = ``aarch64|aarch64_32|arm|i386|loongarch64|mic|mips|mips64|ppc64|ppc64le|x86_64|riscv64|s390x``
- The default value for this option is chosen based on probing the compiler for
- architecture macros (e.g., is ``__x86_64__`` predefined by compiler?).
-
-**LIBOMP_MIC_ARCH** = ``knc|knf``
- Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture) to
- build for. This value is ignored if **LIBOMP_ARCH** does not equal ``mic``.
-
-**LIBOMP_LIB_TYPE** = ``normal|profile|stubs``
- Library type can be ``normal``, ``profile``, or ``stubs``.
-
-**LIBOMP_USE_VERSION_SYMBOLS** = ``ON|OFF``
- Use versioned symbols for building the library. This option only makes sense
- for ELF based libraries where version symbols are supported (Linux*, some BSD*
- variants). It is ``OFF`` by default for Windows* and macOS*, but ``ON`` for
- other Unix based operating systems.
-
-**LIBOMP_ENABLE_SHARED** = ``ON|OFF``
- Build a shared library. If this option is ``OFF``, static OpenMP libraries
- will be built instead of dynamic ones.
-
- .. note::
-
- Static libraries are not supported on Windows*.
-
-**LIBOMP_FORTRAN_MODULES** = ``OFF|ON``
- Create the Fortran modules (requires Fortran compiler).
-
-macOS* Fat Libraries
-""""""""""""""""""""
-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.
-
-.. code-block:: console
-
- $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' ..
- $ make
-
-There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case
-this is an LLVM source tree build. It will only apply for the ``libomp`` library
-avoids having the entire LLVM/Clang build produce universal binaries.
-
-Optional Features
-"""""""""""""""""
-
-**LIBOMP_USE_ADAPTIVE_LOCKS** = ``ON|OFF``
- Include adaptive locks, based on Intel(R) Transactional Synchronization
- Extensions (Intel(R) TSX). This feature is x86 specific and turned ``ON``
- by default for IA-32 architecture and Intel(R) 64 architecture.
-
-**LIBOMP_USE_INTERNODE_ALIGNMENT** = ``OFF|ON``
- Align certain data structures on 4096-byte. This option is useful on
- multi-node systems where a small ``CACHE_LINE`` setting leads to false sharing.
-
-**LIBOMP_OMPT_SUPPORT** = ``ON|OFF``
- Include support for the OpenMP Tools Interface (OMPT).
- This option is supported and ``ON`` by default for x86, x86_64, AArch64,
- PPC64, RISCV64, LoongArch64, and s390x on Linux* and macOS*.
- This option is ``OFF`` if this feature is not supported for the platform.
-
-**LIBOMP_OMPT_OPTIONAL** = ``ON|OFF``
- Include support for optional OMPT functionality. This option is ignored if
- **LIBOMP_OMPT_SUPPORT** is ``OFF``.
-
-**LIBOMP_STATS** = ``OFF|ON``
- Include stats-gathering code.
-
-**LIBOMP_USE_DEBUGGER** = ``OFF|ON``
- Include the friendly debugger interface.
-
-**LIBOMP_USE_HWLOC** = ``OFF|ON``
- Use `OpenMPI's hwloc library <https://www.open-mpi.org/projects/hwloc/>`_ for
- topology detection and affinity.
-
-**LIBOMP_HWLOC_INSTALL_DIR** = ``/path/to/hwloc/install/dir``
- Specify install location of hwloc. The configuration system will look for
- ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in
- ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``. The default is ``/usr/local``.
- This option is only used if **LIBOMP_USE_HWLOC** is ``ON``.
-
-Additional Compiler Flags
-"""""""""""""""""""""""""
-
-These flags are **appended**, they do not overwrite any of the preset flags.
-
-**LIBOMP_CPPFLAGS** = <space-separated flags>
- Additional C preprocessor flags.
-
-**LIBOMP_CXXFLAGS** = <space-separated flags>
- Additional C++ compiler flags.
-
-**LIBOMP_ASMFLAGS** = <space-separated flags>
- Additional assembler flags.
-
-**LIBOMP_LDFLAGS** = <space-separated flags>
- Additional linker flags.
-
-**LIBOMP_LIBFLAGS** = <space-separated flags>
- Additional libraries to link.
-
-**LIBOMP_FFLAGS** = <space-separated flags>
- Additional Fortran compiler flags.
-
-Options for ``libomptarget``
-----------------------------
-
-An installed LLVM package is a prerequisite for building ``libomptarget``
-library. So ``libomptarget`` may only be built in two cases:
-
-- As a project of a regular LLVM build via **LLVM_ENABLE_PROJECTS**,
- **LLVM_EXTERNAL_PROJECTS**, or **LLVM_ENABLE_RUNTIMES** or
-- as a standalone project build that uses a pre-installed LLVM package.
- In this mode one has to make sure that the default CMake
- ``find_package(LLVM)`` call `succeeds <https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure>`_.
-
-**LIBOMPTARGET_OPENMP_HEADER_FOLDER** = ``""``
- Path of the folder that contains ``omp.h``. This is required for testing
- out-of-tree builds.
-
-**LIBOMPTARGET_OPENMP_HOST_RTL_FOLDER** = ``""``
- Path of the folder that contains ``libomp.so``, and ``libLLVMSupport.so``
- when profiling is enabled. This is required for testing.
-
-Options for ``NVPTX device RTL``
---------------------------------
-
-**LIBOMPTARGET_NVPTX_ENABLE_BCLIB** = ``ON|OFF``
- Enable CUDA LLVM bitcode offloading device RTL. This is used for link time
- optimization of the OMP runtime and application code. This option is enabled
- by default if the build system determines that `CMAKE_C_COMPILER` is able to
- compile and link the library.
-
-**LIBOMPTARGET_NVPTX_CUDA_COMPILER** = ``""``
- Location of a CUDA compiler capable of emitting LLVM bitcode. Currently only
- the Clang compiler is supported. This is only used when building the CUDA LLVM
- bitcode offloading device RTL. If unspecified, either the Clang from the build
- itself is used (i.e. an in-tree build with LLVM_ENABLE_PROJECTS including
- clang), or the Clang compiler that the build uses as C compiler
- (CMAKE_C_COMPILER; only if it is Clang). The latter is common for a
- stage2-build or when using -DLLVM_ENABLE_RUNTIMES=openmp.
-
-**LIBOMPTARGET_NVPTX_BC_LINKER** = ``""``
- Location of a linker capable of linking LLVM bitcode objects. This is only
- used when building the CUDA LLVM bitcode offloading device RTL. If
- unspecified, either the llvm-link in that same directory as
- LIBOMPTARGET_NVPTX_CUDA_COMPILER is used, or the llvm-link from the
- same build (available in an in-tree build).
-
-**LIBOMPTARGET_NVPTX_ALTERNATE_HOST_COMPILER** = ``""``
- Host compiler to use with NVCC. This compiler is not going to be used to
- produce any binary. Instead, this is used to overcome the input compiler
- checks done by NVCC. E.g. if using a default host compiler that is not
- compatible with NVCC, this option can be use to pass to NVCC a valid compiler
- to avoid the error.
-
- **LIBOMPTARGET_NVPTX_COMPUTE_CAPABILITIES** = ``35``
- List of CUDA compute capabilities that should be supported by the NVPTX
- device RTL. E.g. for compute capabilities 6.0 and 7.0, the option "60;70"
- should be used. Compute capability 3.5 is the minimum required.
-
- **LIBOMPTARGET_NVPTX_DEBUG** = ``OFF|ON``
- Enable printing of debug messages from the NVPTX device RTL.
-
-**LIBOMPTARGET_LIT_ARGS** = ``""``
- Arguments given to lit. ``make check-libomptarget`` and
- ``make check-libomptarget-*`` are affected. For example, use
- ``LIBOMPTARGET_LIT_ARGS="-j4"`` to force ``lit`` to start only four parallel
- jobs instead of by default the number of threads in the system.
-
-Example Usages of CMake
-=======================
-
-Typical Invocations
--------------------
-
-.. code-block:: console
-
- $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
- $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
- $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc ..
-
-Advanced Builds with Various Options
-------------------------------------
-
-- Build the i386 Linux* library using GCC*
-
- .. code-block:: console
-
- $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 ..
-
-- Build the x86_64 debug Mac library using Clang*
-
- .. code-block:: console
-
- $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug ..
-
-- Build the library (architecture determined by probing compiler) using the
- Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create Fortran
- modules with the Intel(R) Fortran Compiler.
-
- .. code-block:: console
-
- $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on ..
-
-- Have CMake find the C/C++ compiler and specify additional flags for the
- preprocessor and C++ compiler.
-
- .. code-blocks:: console
-
- $ cmake -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' ..
-
-- Build the stubs library
-
- .. code-blocks:: console
-
- $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs ..
-
-**Footnotes**
-
-.. [*] Other names and brands may be claimed as the property of others.
-
-How to Run Tests
-================
-
-There are following check-* make targets for tests.
-
-- ``check-ompt`` (ompt tests under runtime/test/ompt)
-- ``check-ompt-multiplex`` (ompt multiplex tests under tools/multiplex/tests)
-- ``check-ompt-omptest`` (ompt omptest tests under tools/omptest/tests)
-- ``check-libarcher`` (libarcher tests under tools/archer/tests)
-- ``check-libomp`` (libomp tests under runtime/test. This includes check-ompt tests too)
-- ``check-libomptarget-*`` (libomptarget tests for specific target under libomptarget/test)
-- ``check-libomptarget`` (all check-libomptarget-* tests)
-- ``check-openmp`` (combination of all above tests excluding duplicates)
-
-For example, to run all available tests, use ``make check-openmp``.
-
-Options for Tests
-------------------
-Tests use lit framework.
-See `lit documentation <https://llvm.org/docs/CommandGuide/lit.html>`_ for lit options.
-
-**CHECK_OPENMP_ENV** = ``""``
- Default environment variables which test process uses for ``check-openmp``
- separated by space. This can be used for individual targets (``check-ompt``,
- ``check-ompt-multiplex``, ``check-libarcher``, ``check-libomp`` and
- ``check-libomptarget-*``) too. Note that each test still overrides
- environment variables if needed. For example, to change barrier pattern to be
- used from default hyper barrier to hierarchical barrier, run:
-
-.. code-block:: console
-
- $ CHECK_OPENMP_ENV="KMP_PLAIN_BARRIER_PATTERN=hier,hier KMP_FORKJOIN_BARRIER_PATTERN=hier,hier KMP_REDUCTION_BARRIER_PATTERN=hier,hier" make check-openmp
diff --git a/openmp/docs/Building.md b/openmp/docs/Building.md
new file mode 100644
index 0000000000000..bfbdb881b9602
--- /dev/null
+++ b/openmp/docs/Building.md
@@ -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" \
+ -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 install
+ ninja
+ ninja check-openmp
+ ninja install
+```
+
+Compiling OpenMP with the MSVC compiler in a
+[runtimes default build](default_runtimes_build) is currently not supported.
+Offloading is not supported on Windows.
+
+
+### 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
+for the `libomp` library avoids having the entire LLVM/Clang build produce
+universal binaries.
+
+
+## CMake Parameter Reference
+
+CMake configuration parameters specific to OpenMP are prefixed with `OPENMP_`,
+`LIBOMP_`, ``LIBOMPTEST_`, `LIBOMPD_`, or `LIBARCHER_`. Additional configuration
+parameters for the offloading are prefixed with `OFFLOAD_` or `LIBOMPTARGET_`.
+
+The following is a selection of CMake build options recognized by the LLVM
+OpenMP libraries.
+
+[CMAKE_INSTALL_PREFIX]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html
+
+
+### Options for All Libraries
+
+**OPENMP_TEST_C_COMPILER**:FILEPATH, **OPENMP_TEST_CXX_COMPILER**:FILEPATH, **OPENMP_TEST_Fortran_COMPILER**:FILEPATH (defaults: same as `CMAKE_*_COMPILER`)
+: Compiler to use for running regression tests. Regression test compile a small
+OpenMP program using this compiler, link it just-build libraries, and run it to
+test whether everything works properly. This test compiler can be different that
+the compiler the libraries are built with, but many tests are only expected to
+work with Clang from the same git commit.
+
+**OPENMP_TEST_FLAGS**:STRING (default: *empty*), **OPENMP_TEST_OPENMP_FLAGS**:STRING (default: `-fopenmp`)
+: Additional command line flags to use in the regression tests.
+
+**OPENMP_INSTALL_LIBDIR**:STRING (default: `lib${LLVM_LIBDIR_SUFFIX}/${LLVM_DEFAULT_TARGET_TRIPLE}`)
+: Location, relative to [`CMAKE_INSTALL_PREFIX`][CMAKE_INSTALL_PREFIX], where to
+install the OpenMP libraries (`.a` and `.so`)
+
+
+### Options for `libomp`
+
+**LIBOMP_MIC_ARCH** = `knc|knf`
+: Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture) to
+build for. This value is ignored if `LIBOMP_ARCH` does not equal `mic`.
+
+**LIBOMP_LIB_TYPE** = `normal|profile|stubs`
+: Library type can be `normal`, `profile`, or `stubs`.
+
+**LIBOMP_USE_VERSION_SYMBOLS**:BOOL
+: Use versioned symbols for building the library. This option only makes sense
+for ELF based libraries where version symbols are supported (Linux*, some BSD*
+variants). It is `OFF` by default for Windows* and macOS*, but `ON` for
+other Unix based operating systems.
+
+**LIBOMP_ENABLE_SHARED**:BOOL (default: `ON`)
+: Build a shared library. If this option is `OFF`, static OpenMP libraries
+will be built instead of dynamic ones.
+
+:::{note}
+Static libraries are not supported on Windows.
+:::
+
+(LIBOMP_OSX_ARCHITECTURES)=
+**LIBOMP_OSX_ARCHITECTURES**
+: For Mac builds, semicolon separated list of architectures to build for
+universal fat binary.
+
+**LIBOMP_USE_ADAPTIVE_LOCKS**:BOOL
+: Include adaptive locks, based on Intel(R) Transactional Synchronization
+Extensions (Intel(R) TSX). This feature is x86 specific and turned `ON`
+by default for IA-32 architecture and Intel(R) 64 architecture.
+
+**LIBOMP_USE_INTERNODE_ALIGNMENT**:BOOL
+: Align certain data structures on 4096-byte. This option is useful on
+multi-node systems where a small `CACHE_LINE` setting leads to false sharing.
+
+**LIBOMP_STATS**:BOOL
+: Include stats-gathering code.
+
+**LIBOMP_USE_DEBUGGER**:BOOL
+: Include the friendly debugger interface.
+
+(LIBOMP_USE_HWLOC)=
+**LIBOMP_USE_HWLOC**:BOOL
+: Use [OpenMPI's hwloc library](https://www.open-mpi.org/projects/hwloc/) for
+topology detection and affinity.
+
+**LIBOMP_HWLOC_INSTALL_DIR**:PATH
+: Specify install location of hwloc. The configuration system will look for
+`hwloc.h` in `${LIBOMP_HWLOC_INSTALL_DIR}/include` and the library in
+`${LIBOMP_HWLOC_INSTALL_DIR}/lib`. The default is `/usr/local`.
+This option is only used if [`LIBOMP_USE_HWLOC`](LIBOMP_USE_HWLOC) is `ON`.
+
+**LIBOMP_CPPFLAGS** = <space-separated flags>
+: Additional C preprocessor flags.
+
+**LIBOMP_CXXFLAGS** = <space-separated flags>
+: Additional C++ compiler flags.
+
+**LIBOMP_ASMFLAGS** = <space-separated flags>
+: Additional assembler flags.
+
+**LIBOMP_LDFLAGS** = <space-separated flags>
+: Additional linker flags.
+
+**LIBOMP_LIBFLAGS** = <space-separated flags>
+: Additional libraries to link.
+
+**LIBOMP_FFLAGS** = <space-separated flags>
+: Additional Fortran compiler flags.
+
+
+### Options for `libompt`
+
+(LIBOMP_OMPT_SUPPORT)=
+**LIBOMP_OMPT_SUPPORT**:BOOL
+: Include support for the OpenMP Tools Interface (OMPT).
+This option is supported and `ON` by default for x86, x86_64, AArch64,
+PPC64, RISCV64, LoongArch64, and s390x on Linux* and macOS*.
+This option is `OFF` if this feature is not supported for the platform.
+
+**OPENMP_ENABLE_OMPT_TOOLS**:BOOL
+: Enable building ompt based tools for OpenMP.
+
+**LIBOMP_ARCHER_SUPPORT**:BOOL
+: Build libomp with archer support.
+
+**LIBOMP_OMPT_OPTIONAL**:BOOL
+: Include support for optional OMPT functionality. This option is ignored if
+[`LIBOMP_OMPT_SUPPORT`](LIBOMP_OMPT_SUPPORT) is `OFF`.
+
+**LIBOMPTEST_INSTALL_COMPONENTS**: BOOL (default: `OFF`)
+: Whether to also copy `libomptest.so` into
+[`CMAKE_INSTALL_PREFIX`][CMAKE_INSTALL_PREFIX] during `ninja install`.
+
+
+### Options for offload/`libomptarget`
+
+**LIBOMPTARGET_OPENMP_HEADER_FOLDER**:PATH
+: Path of the folder that contains `omp.h`. This is required for testing
+out-of-tree builds.
+
+**LIBOMPTARGET_OPENMP_HOST_RTL_FOLDER**:PATH
+: Path of the folder that contains `libomp.so`, and `libLLVMSupport.so`
+when profiling is enabled. This is required for testing.
+
+**LIBOMPTARGET_LIT_ARGS**:STRING
+: Arguments given to lit. `make check-libomptarget` and
+`make check-libomptarget-*` are affected. For example, use
+`LIBOMPTARGET_LIT_ARGS="-j4"` to force `lit` to start only four parallel
+jobs instead of by default the number of threads in the system.
+
+**LIBOMPTARGET_ENABLE_DEBUG**:BOOL
+: Enable printing of debug messages with the `LIBOMPTARGET_DEBUG=1` environment
+variable.
+
+**LIBOMPTARGET_PLUGINS_TO_BUILD** = semicolon-separated list of `cuda|amdgpu|host` or `all` (default: `all`)
+: List of offload plugins to build.
+
+(LIBOMPTARGET_DLOPEN_PLUGINS)=
+**LIBOMPTARGET_DLOPEN_PLUGINS** = semicolon-separated list of `cuda|amdgpu` or `all` (default: `${LIBOMPTARGET_PLUGINS_TO_BUILD}`)
+: List of plugins to use `dlopen` instead of the `ld.so` dynamic linker for
+runtime linking. `dlopen` does not require the vendor runtime libraries to be
+present at build-time of OpenMP, but imposes higher runtime overhead.
diff --git a/openmp/docs/SupportAndFAQ.rst b/openmp/docs/SupportAndFAQ.rst
index f5a84784c8de8..8d85a63664f63 100644
--- a/openmp/docs/SupportAndFAQ.rst
+++ b/openmp/docs/SupportAndFAQ.rst
@@ -47,79 +47,6 @@ All patches go through the regular `LLVM review process
<https://llvm.org/docs/Contributing.html#how-to-submit-a-patch>`_.
-.. _build_offload_capable_compiler:
-
-Q: How to build an OpenMP GPU offload capable compiler?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The easiest way to create an offload capable compiler is to use the provided
-CMake cache file. This will enable the projects and runtimes necessary for
-offloading as well as some extra options.
-
-.. code-block:: sh
-
- $> cd llvm-project # The llvm-project checkout
- $> mkdir build
- $> cd build
- $> cmake ../llvm -G Ninja \
- -C ../offload/cmake/caches/Offload.cmake \ # The preset cache file
- -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type
- -DCMAKE_INSTALL_PREFIX=<PATH> \ # Where the libraries will live
- $> ninja install
-
-To manually build an *effective* OpenMP offload capable compiler, only one extra CMake
-option, ``LLVM_ENABLE_RUNTIMES="openmp;offload"``, is needed when building LLVM (Generic
-information about building LLVM is available `here
-<https://llvm.org/docs/GettingStarted.html>`__.). Make sure all backends that
-are targeted by OpenMP are enabled. That can be done by adjusting the CMake
-option ``LLVM_TARGETS_TO_BUILD``. The corresponding targets for offloading to AMD
-and Nvidia GPUs are ``"AMDGPU"`` and ``"NVPTX"``, respectively. By default,
-Clang will be built with all backends enabled. When building with
-``LLVM_ENABLE_RUNTIMES="openmp"`` OpenMP should not be enabled in
-``LLVM_ENABLE_PROJECTS`` because it is enabled by default.
-
-Support for the device library comes from a separate build of the OpenMP library
-that targets the GPU architecture. Building it requires enabling the runtime
-targets, or setting the target manually when doing a standalone build. This is
-done with the ``LLVM_RUNTIME_TARGETS`` option and then enabling the OpenMP
-runtime for the GPU target via ``RUNTIMES_<triple>_LLVM_ENABLE_RUNTIMES``.
-It's possible to set different flags for each device library by using
-``RUNTIMES_<triple>_CMAKE_CXX_FLAGS``. Refer to the cache file for the specific
-invocation.
-
-For Nvidia offload, please see :ref:`build_nvidia_offload_capable_compiler`.
-For AMDGPU offload, please see :ref:`build_amdgpu_offload_capable_compiler`.
-
-.. note::
- The compiler that generates the offload code should be the same (version) as
- the compiler that builds the OpenMP device runtimes. The OpenMP host runtime
- can be built by a different compiler.
-
-.. _advanced_builds: https://llvm.org//docs/AdvancedBuilds.html
-
-.. _build_nvidia_offload_capable_compiler:
-
-Q: How to build an OpenMP Nvidia offload capable compiler?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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`` 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.
-
-.. _build_amdgpu_offload_capable_compiler:
-
-Q: How to build an OpenMP AMDGPU offload capable compiler?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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`` list.
-
Q: What are the known limitations of OpenMP AMDGPU offload?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t b/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t
index ff43186da0305..946cca17c2dd3 100644
--- a/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t
+++ b/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t
@@ -536,3 +536,9 @@ div.body div.math p {
span.eqno {
float: right;
}
+
+/* -- defintion list -------------------------------------------------------- */
+
+dl.simple dt {
+ text-align: left
+}
diff --git a/openmp/docs/conf.py b/openmp/docs/conf.py
index a11814c6ec12c..3bc0d2aae30c3 100644
--- a/openmp/docs/conf.py
+++ b/openmp/docs/conf.py
@@ -26,13 +26,23 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"]
+extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx", "myst_parser"]
+
+# Add path for llvm_slug module.
+sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs")))
+
+
+myst_enable_extensions = ["substitution", "colon_fence", "deflist"]
+
+# Automatic anchors for markdown titles
+myst_heading_anchors = 6
+myst_heading_slug_func = "llvm_slug.make_slug"
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
# The encoding of source files.
# source_encoding = 'utf-8-sig'
diff --git a/openmp/docs/index.rst b/openmp/docs/index.rst
index 97ded910782d0..def98df57817c 100644
--- a/openmp/docs/index.rst
+++ b/openmp/docs/index.rst
@@ -11,25 +11,27 @@
:maxdepth: 1
LLVM/OpenMP Documentation <self>
+ Building
-Building LLVM/OpenMP Offloading
-===============================
-
-Building LLVM/OpenMP with offloading support is fully documented in the
-:doc:`Support and FAQ <SupportAndFAQ>` page. For a quick start, we recommend
-the following template.
-
-.. code-block:: sh
+Getting Started
+===============
- $> cd llvm-project # The llvm-project checkout
- $> mkdir build
- $> cd build
- $> cmake ../llvm -G Ninja \
- -C ../offload/cmake/caches/Offload.cmake \ # The preset cache file
- -DCMAKE_BUILD_TYPE=<Debug|Release> \ # Select build type
- -DCMAKE_INSTALL_PREFIX=<PATH> \ # Where the libraries will live
- $> ninja install
+Building LLVM/OpenMP is fully documented on the
+:doc:`Building` page. For a quick start, we recommend the following template
+for building OpenMP with offloading support.
+
+.. code-block:: console
+
+ $ git clone https://github.com/llvm/llvm-project.git
+ $ cd llvm-project
+ $ mkdir build
+ $ cd build
+ $ cmake ../llvm -G Ninja \
+ -C ../offload/cmake/caches/Offload.cmake \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=<PATH>
+ $ ninja install # Builds all files and installs files to <PATH>/bin, <PATH>/lib, etc
LLVM/OpenMP Design & Overview
=============================
>From 86d90e2e019df6f5dbf5ef68d1d5b637db2d2e75 Mon Sep 17 00:00:00 2001
From: Michael Kruse <llvm-project at meinersbur.de>
Date: Thu, 15 Jan 2026 16:40:10 +0100
Subject: [PATCH 2/3] Apply darker
---
openmp/docs/conf.py | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/openmp/docs/conf.py b/openmp/docs/conf.py
index 3bc0d2aae30c3..d7002ee033147 100644
--- a/openmp/docs/conf.py
+++ b/openmp/docs/conf.py
@@ -26,7 +26,12 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx", "myst_parser"]
+extensions = [
+ "sphinx.ext.todo",
+ "sphinx.ext.mathjax",
+ "sphinx.ext.intersphinx",
+ "myst_parser",
+]
# Add path for llvm_slug module.
sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs")))
>From 3e823c3ce68e90bb0c25769f6760d4886235db90 Mon Sep 17 00:00:00 2001
From: Michael Kruse <llvm-project at meinersbur.de>
Date: Thu, 15 Jan 2026 16:49:16 +0100
Subject: [PATCH 3/3] Add manual for ompd options
---
openmp/docs/Building.md | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/openmp/docs/Building.md b/openmp/docs/Building.md
index bfbdb881b9602..c239fc3e35b7a 100644
--- a/openmp/docs/Building.md
+++ b/openmp/docs/Building.md
@@ -307,7 +307,7 @@ This option is only used if [`LIBOMP_USE_HWLOC`](LIBOMP_USE_HWLOC) is `ON`.
: Additional Fortran compiler flags.
-### Options for `libompt`
+### Options for OMPT Support
(LIBOMP_OMPT_SUPPORT)=
**LIBOMP_OMPT_SUPPORT**:BOOL
@@ -331,6 +331,15 @@ This option is `OFF` if this feature is not supported for the platform.
[`CMAKE_INSTALL_PREFIX`][CMAKE_INSTALL_PREFIX] during `ninja install`.
+### Options for `libompd`
+
+**LIBOMP_OMPD_SUPPORT**:BOOL
+: Enable building the libompd library.
+
+**LIBOMPD_LD_STD_FLAGS**:STRING
+: Use `-stdlibc++` instead of `-libc++` library for C++.
+
+
### Options for offload/`libomptarget`
**LIBOMPTARGET_OPENMP_HEADER_FOLDER**:PATH
More information about the Openmp-commits
mailing list