forked from OSchip/llvm-project
354 lines
13 KiB
ReStructuredText
354 lines
13 KiB
ReStructuredText
========================================
|
|
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_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|arm|i386|mic|mips|mips64|ppc64|ppc64le|x86_64|riscv64``
|
|
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 and RISCV64 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.
|
|
|
|
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.
|