reference, declarationdefinition
definition → references, declarations, derived classes, virtual overrides
reference to multiple definitions → definitions
unreferenced
    1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122
  123
  124
  125
  126
  127
  128
  129
  130
  131
  132
  133
  134
  135
  136
  137
  138
  139
  140
  141
  142
  143
  144
  145
  146
  147
  148
  149
  150
  151
  152
  153
  154
  155
  156
  157
  158
  159
  160
  161
  162
  163
  164
  165
  166
  167
  168
  169
  170
  171
  172
  173
  174
  175
  176
  177
  178
  179
  180
  181
  182
  183
  184
  185
  186
  187
  188
  189
  190
  191
  192
  193
  194
  195
  196
  197
  198
  199
  200
  201
  202
  203
  204
  205
  206
  207
  208
  209
  210
  211
  212
  213
  214
  215
  216
  217
  218
  219
  220
  221
  222
  223
  224
  225
  226
  227
  228
  229
  230
  231
  232
  233
  234
  235
  236
  237
  238
  239
  240
  241
  242
  243
  244
  245
  246
  247
  248
  249
  250
  251
  252
  253
  254
  255
  256
  257
  258
  259
  260
  261
  262
  263
  264
  265
  266
  267
  268
  269
  270
  271
  272
  273
  274
  275
  276
  277
  278
  279
  280
  281
  282
  283
  284
  285
  286
  287
  288
  289
  290
  291
  292
  293
  294
  295
  296
  297
  298
  299
  300
  301
  302
  303
  304
  305
  306
  307
  308
  309
  310
  311
  312
  313
  314
  315
  316
  317
  318
  319
  320
  321
  322
  323
  324
  325
  326
  327
  328
  329
  330
  331
  332
  333
  334
  335
  336
  337
  338
  339
  340
  341
  342
  343
========================================
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.

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 and the CMake C compiler is
  Clang, then Clang is used.

**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
  and the CMake C compiler is Clang and there exists a llvm-link binary in the
  directory containing Clang, then this llvm-link binary is used.

**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 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.