[Openmp-commits] [openmp] [OpenMP][docs] Revise building manual (PR #176175)
Michael Kruse via Openmp-commits
openmp-commits at lists.llvm.org
Thu Jan 15 10:52:25 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/4] [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/4] 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/4] 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
>From 53a677988e4e2d9b2f9c19307fbc0bdacbb108dd Mon Sep 17 00:00:00 2001
From: Michael Kruse <llvm-project at meinersbur.de>
Date: Thu, 15 Jan 2026 19:52:06 +0100
Subject: [PATCH 4/4] Add @jhuber6's suggestion (with modification)
---
openmp/docs/Building.md | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/openmp/docs/Building.md b/openmp/docs/Building.md
index c239fc3e35b7a..5d82cdf99a9e9 100644
--- a/openmp/docs/Building.md
+++ b/openmp/docs/Building.md
@@ -120,8 +120,10 @@ 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.
+`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
More information about the Openmp-commits
mailing list