forked from OSchip/llvm-project
308 lines
11 KiB
ReStructuredText
308 lines
11 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 <http://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**.
|
|
|
|
Options for ``libomp``
|
|
----------------------
|
|
|
|
**LIBOMP_ARCH** = ``aarch64|arm|i386|mic|mips|mips64|ppc64|ppc64le|x86_64``
|
|
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_OMP_VERSION** = ``50|45|40|30``
|
|
OpenMP version to build for. Older versions will disable certain
|
|
functionality and entry points.
|
|
|
|
**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, and
|
|
PPC64 on Linux*, Windows*, 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_CFLAGS** = <space-separated flags>
|
|
Additional C compiler 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``
|
|
----------------------------
|
|
|
|
**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``. This is required for testing
|
|
out-of-tree builds.
|
|
|
|
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 C
|
|
compiler, preprocessor, and C++ compiler.
|
|
|
|
.. code-blocks:: console
|
|
|
|
$ cmake -DLIBOMP_CFLAGS='-specific-flag' -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.
|