shylie/llvm-project
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

[OpenMP][docs] Revise building manual (#176175)

Browse Source 
Go into more detail on the two non-legacy build modes. 

I decided use create a dedicated document documention the build process.
`index.rst` only keeps the "Getting Started" part. `README.rst` is
vastly outdated with the still valid parts integrated into the new
documentation. `SupportAndFAQ.rst` is unstructured and keeps only the
non-building parts.

The the new building document is written in Meltdown, following the
decision from LLVM.
This commit is contained in:
Michael Kruse 2026-01-28 14:13:41 +01:00 committed by GitHub
parent eb64fb6d12
commit dd76d3382c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 484 additions and 526 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

396
openmp/README.rst
View File

@ -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

404
openmp/docs/Building.md Normal file
View File

@ -0,0 +1,404 @@
# 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.
```{contents}
:depth: 3
```
## 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 (Build together with LLVM)
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"
```
Note that this requires having an `aarch64-linux-gnu` cross-compilation
toolchain to be available on the host system. While Clang is able to
cross-compile this triple when `LLVM_TARGETS_TO_BUILD` includes `AArch64` (which
it does by default), a linker and certain libraries such as pthread are required
as well.
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
might interfere with the system's OpenMP installation, such as `omp.h` from
gcc.
(default_runtimes_build)=
### Runtimes Default/Standalone Build (Using a pre-built LLVM)
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
# Building LLVM
mkdir build
cd build
cmake ../llvm -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=<PATH> \
-DLLVM_ENABLE_PROJECTS=clang
ninja
ninja install
cd ..
# Building the OpenMP libraries
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
```
Here, `../build` is the path the build of LLVM completed in the first step. 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. `LLVM_BINARY_DIR` can also be omitted in which case testing
(`ninja check-openmp`) is disabled.
The `CMAKE_INSTALL_PREFIX` can be the same, but does not need to. Using the same
path will allow Clang to automatically find the OpenMP files.
(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;lld" \
-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
```
The additional `LLVM_ENABLE_PROJECTS=lld` is needed to compile LLVM
bitcode of the GPU-side device runtime which uses LTO.
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, as well
as lld, and that `AMDGPU` and `NVPTX` is enabled in its
``LLVM_TARGETS_TO_BUILD`` configuration (which it is by default).
In practice the setup above will probably missing requirements for actually
running programs on GPUs such as device-side toolchain libraries. A more
complete build 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
```
## CMake Configuration 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_FLAGS**:STRING (default: *empty*), **OPENMP_TEST_OPENMP_FLAGS**:STRING (default: `-fopenmp`)
: Additional command line flags passed to Clang when compiling 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 OMPT
(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 `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 `libomptarget`/offload
**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.

73
openmp/docs/SupportAndFAQ.rst
View File

@ -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?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

45
openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t vendored
View File

@ -76,8 +76,15 @@ h1, h2, h3, h4 {
margin-bottom: .8em;
}
h1 {
h1, h1 a {
color: {{ theme_headercolor1 }};
text-decoration: none!important;
}
h2 {
padding-bottom: .5em;
border-bottom: 1px solid #3465a4;
text-decoration: none!important;
}
h2 {
@ -85,6 +92,11 @@ h2 {
border-bottom: 1px solid {{ theme_headercolor2 }};
}
h2 a, h3 a, h4 a {
color: {{ theme_headercolor2 }};
text-decoration: none!important;
}
a.headerlink {
visibility: hidden;
color: #dddddd;
@ -536,3 +548,34 @@ div.body div.math p {
span.eqno {
float: right;
}
/* -- definition list -------------------------------------------------------- */
dl.simple dt {
text-align: left
}
/* -- topics ---------------------------------------------------------------- */
nav.contents,
aside.topic,
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
.document nav p {
margin-bottom: 0;
}
.document nav ul {
margin-top: 0;
margin-bottom: 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}

19
openmp/docs/conf.py
View File

@ -26,13 +26,28 @@ from datetime import date
# 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'

30
openmp/docs/index.rst
View File

@ -11,25 +11,27 @@
:maxdepth: 1
LLVM/OpenMP Documentation <self>
Building
Building LLVM/OpenMP Offloading
===============================
Getting Started
===============
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.
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:: sh
.. code-block:: console
$> 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
$ 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
=============================

18
openmp/runtime/README.txt
View File

@ -23,25 +23,9 @@ www.doxygen.org.
How to Build the LLVM* OpenMP* Runtime Library
==============================================
In-tree build:
$ cd where-you-want-to-live
Check out openmp into llvm/projects
$ cd where-you-want-to-build
$ mkdir build && cd build
$ cmake path/to/llvm -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
$ make omp
For build instructions, please see https://openmp.llvm.org/Building.html.
Out-of-tree build:
$ cd where-you-want-to-live
Check out openmp
$ cd where-you-want-to-live/openmp/runtime
$ mkdir build && cd build
$ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
$ make
For details about building, please look at README.rst in the parent directory.
Architectures Supported
=======================

25
openmp/runtime/doc/doxygen/libomp_interface.h
View File

@ -26,30 +26,9 @@ The aim here is to explain the interface from the compiler to the runtime.
The overall design is described, and each function in the interface
has its own description. (At least, that's the ambition, we may not be there yet).
@section sec_building Quickly Building the Runtime
For the impatient, we cover building the runtime as the first topic here.
@section sec_building Building the Runtime
CMake is used to build the OpenMP runtime. For details and a full list of options for the CMake build system,
see <tt>README.rst</tt> in the source code repository. These instructions will provide the most typical build.
In-LLVM-tree build:.
@code
$ cd where-you-want-to-live
Check out openmp into llvm/projects
$ cd where-you-want-to-build
$ mkdir build && cd build
$ cmake path/to/llvm -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
$ make omp
@endcode
Out-of-LLVM-tree build:
@code
$ cd where-you-want-to-live
Check out openmp
$ cd where-you-want-to-live/openmp
$ mkdir build && cd build
$ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
$ make
@endcode
For build instructions, please see https://openmp.llvm.org/Building.html.
@section sec_supported Supported RTL Build Configurations