openmp/README.rst

   1 ========================================
   2 How to Build the LLVM* OpenMP* Libraries
   3 ========================================
   4 This repository requires `CMake <http://www.cmake.org/>`_ v2.8.0 or later.  LLVM
   5 and Clang need a more recent version which also applies for in-tree builds.  For
   6 more information than available in this document please see
   7 `LLVM's CMake documentation <https://llvm.org/docs/CMake.html>`_ and the
   8 `official documentation <https://cmake.org/cmake/help/v2.8.0/cmake.html>`_.
   9
  10 .. contents::
  11    :local:
  12
  13 How to Call CMake Initially, then Repeatedly
  14 ============================================
  15 - When calling CMake for the first time, all needed compiler options must be
  16   specified on the command line.  After this initial call to CMake, the compiler
  17   definitions must not be included for further calls to CMake.  Other options
  18   can be specified on the command line multiple times including all definitions
  19   in the build options section below.
  20 - Example of configuring, building, reconfiguring, rebuilding:
  21
  22   .. code-block:: console
  23
  24     $ mkdir build
  25     $ cd build
  26     $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..  # Initial configuration
  27     $ make
  28     ...
  29     $ make clean
  30     $ cmake -DCMAKE_BUILD_TYPE=Debug ..                               # Second configuration
  31     $ make
  32     ...
  33     $ rm -rf *
  34     $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..        # Third configuration
  35     $ make
  36
  37 - Notice in the example how the compiler definitions are only specified for an
  38   empty build directory, but other build options are used at any time.
  39 - The file ``CMakeCache.txt`` which is created after the first call to CMake is
  40   a configuration file which holds all values for the build options.  These
  41   values can be changed using a text editor to modify ``CMakeCache.txt`` as
  42   opposed to using definitions on the command line.
  43 - To have CMake create a particular type of build generator file simply include
  44   the ``-G <Generator name>`` option:
  45
  46   .. code-block:: console
  47
  48     $ cmake -G "Unix Makefiles" ...
  49
  50   You can see a list of generators CMake supports by executing the cmake command
  51   with no arguments.
  52
  53 Instructions to Build
  54 =====================
  55 .. code-block:: console
  56
  57  $ cd openmp_top_level/ [ this directory with libomptarget/, runtime/, etc. ]
  58  $ mkdir build
  59  $ cd build
  60
  61  [ Unix* Libraries ]
  62  $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
  63
  64  [ Windows* Libraries ]
  65  $ cmake -G <Generator Type> -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release ..
  66
  67  $ make
  68  $ make install
  69
  70 CMake Options
  71 =============
  72 Builds with CMake can be customized by means of options as already seen above.
  73 One possibility is to pass them via the command line:
  74
  75 .. code-block:: console
  76
  77   $ cmake -DOPTION=<value> path/to/source
  78
  79 .. note:: The first value listed is the respective default for that option.
  80
  81 Generic Options
  82 ---------------
  83 For full documentation consult the CMake manual or execute
  84 ``cmake --help-variable VARIABLE_NAME`` to get information about a specific
  85 variable.
  86
  87 **CMAKE_BUILD_TYPE** = ``Release|Debug|RelWithDebInfo``
  88   Build type can be ``Release``, ``Debug``, or ``RelWithDebInfo`` which chooses
  89   the optimization level and presence of debugging symbols.
  90
  91 **CMAKE_C_COMPILER** = <C compiler name>
  92   Specify the C compiler.
  93
  94 **CMAKE_CXX_COMPILER** = <C++ compiler name>
  95   Specify the C++ compiler.
  96
  97 **CMAKE_Fortran_COMPILER** = <Fortran compiler name>
  98   Specify the Fortran compiler. This option is only needed when
  99   **LIBOMP_FORTRAN_MODULES** is ``ON`` (see below).  So typically, a Fortran
 100   compiler is not needed during the build.
 101
 102 **CMAKE_ASM_MASM_COMPILER** = ``ml|ml64``
 103   This option is only relevant for Windows*.
 104
 105 Options for all Libraries
 106 -------------------------
 107
 108 **OPENMP_ENABLE_WERROR** = ``OFF|ON``
 109   Treat warnings as errors and fail, if a compiler warning is triggered.
 110
 111 **OPENMP_LIBDIR_SUFFIX** = ``""``
 112   Extra suffix to append to the directory where libraries are to be installed.
 113
 114 **OPENMP_TEST_C_COMPILER** = ``${CMAKE_C_COMPILER}``
 115   Compiler to use for testing. Defaults to the compiler that was also used for
 116   building.
 117
 118 **OPENMP_TEST_CXX_COMPILER** = ``${CMAKE_CXX_COMPILER}``
 119   Compiler to use for testing. Defaults to the compiler that was also used for
 120   building.
 121
 122 **OPENMP_TEST_Fortran_COMPILER** = ``${CMAKE_Fortran_COMPILER}``
 123   Compiler to use for testing. Defaults to the compiler that was also used for
 124   building. Will default to flang if build is in-tree.
 125
 126 **OPENMP_LLVM_TOOLS_DIR** = ``/path/to/built/llvm/tools``
 127   Additional path to search for LLVM tools needed by tests.
 128
 129 **OPENMP_LLVM_LIT_EXECUTABLE** = ``/path/to/llvm-lit``
 130   Specify full path to ``llvm-lit`` executable for running tests.  The default
 131   is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
 132
 133 **OPENMP_FILECHECK_EXECUTABLE** = ``/path/to/FileCheck``
 134   Specify full path to ``FileCheck`` executable for running tests.  The default
 135   is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
 136
 137 **OPENMP_NOT_EXECUTABLE** = ``/path/to/not``
 138   Specify full path to ``not`` executable for running tests.  The default
 139   is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
 140
 141 Options for ``libomp``
 142 ----------------------
 143
 144 **LIBOMP_ARCH** = ``aarch64|arm|i386|loongarch64|mic|mips|mips64|ppc64|ppc64le|x86_64|riscv64|s390x``
 145   The default value for this option is chosen based on probing the compiler for
 146   architecture macros (e.g., is ``__x86_64__`` predefined by compiler?).
 147
 148 **LIBOMP_MIC_ARCH** = ``knc|knf``
 149   Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture) to
 150   build for.  This value is ignored if **LIBOMP_ARCH** does not equal ``mic``.
 151
 152 **LIBOMP_LIB_TYPE** = ``normal|profile|stubs``
 153   Library type can be ``normal``, ``profile``, or ``stubs``.
 154
 155 **LIBOMP_USE_VERSION_SYMBOLS** = ``ON|OFF``
 156   Use versioned symbols for building the library.  This option only makes sense
 157   for ELF based libraries where version symbols are supported (Linux*, some BSD*
 158   variants).  It is ``OFF`` by default for Windows* and macOS*, but ``ON`` for
 159   other Unix based operating systems.
 160
 161 **LIBOMP_ENABLE_SHARED** = ``ON|OFF``
 162   Build a shared library.  If this option is ``OFF``, static OpenMP libraries
 163   will be built instead of dynamic ones.
 164
 165   .. note::
 166
 167     Static libraries are not supported on Windows*.
 168
 169 **LIBOMP_FORTRAN_MODULES** = ``OFF|ON``
 170   Create the Fortran modules (requires Fortran compiler).
 171
 172 macOS* Fat Libraries
 173 """"""""""""""""""""
 174 On macOS* machines, it is possible to build universal (or fat) libraries which
 175 include both i386 and x86_64 architecture objects in a single archive.
 176
 177 .. code-block:: console
 178
 179   $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' ..
 180   $ make
 181
 182 There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case
 183 this is an LLVM source tree build. It will only apply for the ``libomp`` library
 184 avoids having the entire LLVM/Clang build produce universal binaries.
 185
 186 Optional Features
 187 """""""""""""""""
 188
 189 **LIBOMP_USE_ADAPTIVE_LOCKS** = ``ON|OFF``
 190   Include adaptive locks, based on Intel(R) Transactional Synchronization
 191   Extensions (Intel(R) TSX).  This feature is x86 specific and turned ``ON``
 192   by default for IA-32 architecture and Intel(R) 64 architecture.
 193
 194 **LIBOMP_USE_INTERNODE_ALIGNMENT** = ``OFF|ON``
 195   Align certain data structures on 4096-byte.  This option is useful on
 196   multi-node systems where a small ``CACHE_LINE`` setting leads to false sharing.
 197
 198 **LIBOMP_OMPT_SUPPORT** = ``ON|OFF``
 199   Include support for the OpenMP Tools Interface (OMPT).
 200   This option is supported and ``ON`` by default for x86, x86_64, AArch64,
 201   PPC64, RISCV64, LoongArch64, and s390x on Linux* and macOS*.
 202   This option is ``OFF`` if this feature is not supported for the platform.
 203
 204 **LIBOMP_OMPT_OPTIONAL** = ``ON|OFF``
 205   Include support for optional OMPT functionality.  This option is ignored if
 206   **LIBOMP_OMPT_SUPPORT** is ``OFF``.
 207
 208 **LIBOMP_STATS** = ``OFF|ON``
 209   Include stats-gathering code.
 210
 211 **LIBOMP_USE_DEBUGGER** = ``OFF|ON``
 212   Include the friendly debugger interface.
 213
 214 **LIBOMP_USE_HWLOC** = ``OFF|ON``
 215   Use `OpenMPI's hwloc library <https://www.open-mpi.org/projects/hwloc/>`_ for
 216   topology detection and affinity.
 217
 218 **LIBOMP_HWLOC_INSTALL_DIR** = ``/path/to/hwloc/install/dir``
 219   Specify install location of hwloc.  The configuration system will look for
 220   ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in
 221   ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``.  The default is ``/usr/local``.
 222   This option is only used if **LIBOMP_USE_HWLOC** is ``ON``.
 223
 224 Additional Compiler Flags
 225 """""""""""""""""""""""""
 226
 227 These flags are **appended**, they do not overwrite any of the preset flags.
 228
 229 **LIBOMP_CPPFLAGS** = <space-separated flags>
 230   Additional C preprocessor flags.
 231
 232 **LIBOMP_CXXFLAGS** = <space-separated flags>
 233   Additional C++ compiler flags.
 234
 235 **LIBOMP_ASMFLAGS** = <space-separated flags>
 236   Additional assembler flags.
 237
 238 **LIBOMP_LDFLAGS** = <space-separated flags>
 239   Additional linker flags.
 240
 241 **LIBOMP_LIBFLAGS** = <space-separated flags>
 242   Additional libraries to link.
 243
 244 **LIBOMP_FFLAGS** = <space-separated flags>
 245   Additional Fortran compiler flags.
 246
 247 Options for ``libomptarget``
 248 ----------------------------
 249
 250 An installed LLVM package is a prerequisite for building ``libomptarget``
 251 library. So ``libomptarget`` may only be built in two cases:
 252
 253 - As a project of a regular LLVM build via **LLVM_ENABLE_PROJECTS**,
 254   **LLVM_EXTERNAL_PROJECTS**, or **LLVM_ENABLE_RUNTIMES** or
 255 - as a standalone project build that uses a pre-installed LLVM package.
 256   In this mode one has to make sure that the default CMake
 257   ``find_package(LLVM)`` call `succeeds <https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure>`_.
 258
 259 **LIBOMPTARGET_OPENMP_HEADER_FOLDER** = ``""``
 260   Path of the folder that contains ``omp.h``.  This is required for testing
 261   out-of-tree builds.
 262
 263 **LIBOMPTARGET_OPENMP_HOST_RTL_FOLDER** = ``""``
 264   Path of the folder that contains ``libomp.so``, and ``libLLVMSupport.so``
 265   when profiling is enabled.  This is required for testing.
 266
 267 Options for ``NVPTX device RTL``
 268 --------------------------------
 269
 270 **LIBOMPTARGET_NVPTX_ENABLE_BCLIB** = ``ON|OFF``
 271   Enable CUDA LLVM bitcode offloading device RTL. This is used for link time
 272   optimization of the OMP runtime and application code. This option is enabled
 273   by default if the build system determines that `CMAKE_C_COMPILER` is able to
 274   compile and link the library.
 275
 276 **LIBOMPTARGET_NVPTX_CUDA_COMPILER** = ``""``
 277   Location of a CUDA compiler capable of emitting LLVM bitcode. Currently only
 278   the Clang compiler is supported. This is only used when building the CUDA LLVM
 279   bitcode offloading device RTL. If unspecified, either the Clang from the build
 280   itself is used (i.e. an in-tree build with LLVM_ENABLE_PROJECTS including
 281   clang), or the Clang compiler that the build uses as C compiler
 282   (CMAKE_C_COMPILER; only if it is Clang). The latter is common for a
 283   stage2-build or when using -DLLVM_ENABLE_RUNTIMES=openmp.
 284
 285 **LIBOMPTARGET_NVPTX_BC_LINKER** = ``""``
 286   Location of a linker capable of linking LLVM bitcode objects. This is only
 287   used when building the CUDA LLVM bitcode offloading device RTL. If
 288   unspecified, either the llvm-link in that same directory as
 289   LIBOMPTARGET_NVPTX_CUDA_COMPILER is used, or the llvm-link from the
 290   same build (available in an in-tree build).
 291
 292 **LIBOMPTARGET_NVPTX_ALTERNATE_HOST_COMPILER** = ``""``
 293   Host compiler to use with NVCC. This compiler is not going to be used to
 294   produce any binary. Instead, this is used to overcome the input compiler
 295   checks done by NVCC. E.g. if using a default host compiler that is not
 296   compatible with NVCC, this option can be use to pass to NVCC a valid compiler
 297   to avoid the error.
 298
 299  **LIBOMPTARGET_NVPTX_COMPUTE_CAPABILITIES** = ``35``
 300   List of CUDA compute capabilities that should be supported by the NVPTX
 301   device RTL. E.g. for compute capabilities 6.0 and 7.0, the option "60;70"
 302   should be used. Compute capability 3.5 is the minimum required.
 303
 304  **LIBOMPTARGET_NVPTX_DEBUG** = ``OFF|ON``
 305   Enable printing of debug messages from the NVPTX device RTL.
 306
 307 **LIBOMPTARGET_LIT_ARGS** = ``""``
 308   Arguments given to lit. ``make check-libomptarget`` and
 309   ``make check-libomptarget-*`` are affected. For example, use
 310   ``LIBOMPTARGET_LIT_ARGS="-j4"`` to force ``lit`` to start only four parallel
 311   jobs instead of by default the number of threads in the system.
 312
 313 Example Usages of CMake
 314 =======================
 315
 316 Typical Invocations
 317 -------------------
 318
 319 .. code-block:: console
 320
 321   $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
 322   $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
 323   $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc ..
 324
 325 Advanced Builds with Various Options
 326 ------------------------------------
 327
 328 - Build the i386 Linux* library using GCC*
 329
 330   .. code-block:: console
 331
 332     $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 ..
 333
 334 - Build the x86_64 debug Mac library using Clang*
 335
 336   .. code-block:: console
 337
 338     $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug ..
 339
 340 - Build the library (architecture determined by probing compiler) using the
 341   Intel(R) C Compiler and the Intel(R) C++ Compiler.  Also, create Fortran
 342   modules with the Intel(R) Fortran Compiler.
 343
 344   .. code-block:: console
 345
 346     $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on ..
 347
 348 - Have CMake find the C/C++ compiler and specify additional flags for the
 349   preprocessor and C++ compiler.
 350
 351   .. code-blocks:: console
 352
 353     $ cmake -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' ..
 354
 355 - Build the stubs library
 356
 357   .. code-blocks:: console
 358
 359     $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs ..
 360
 361 **Footnotes**
 362
 363 .. [*] Other names and brands may be claimed as the property of others.
 364
 365 How to Run Tests
 366 ================
 367
 368 There are following check-* make targets for tests.
 369
 370 - ``check-ompt`` (ompt tests under runtime/test/ompt)
 371 - ``check-ompt-multiplex`` (ompt multiplex tests under tools/multiplex/tests)
 372 - ``check-libarcher`` (libarcher tests under tools/archer/tests)
 373 - ``check-libomp`` (libomp tests under runtime/test. This includes check-ompt tests too)
 374 - ``check-libomptarget-*`` (libomptarget tests for specific target under libomptarget/test)
 375 - ``check-libomptarget`` (all check-libomptarget-* tests)
 376 - ``check-openmp`` (combination of all above tests excluding duplicates)
 377
 378 For example, to run all available tests, use ``make check-openmp``.
 379
 380 Options for Tests
 381 ------------------
 382 Tests use lit framework.
 383 See `lit documentation <https://llvm.org/docs/CommandGuide/lit.html>`_ for lit options.
 384
 385 **CHECK_OPENMP_ENV** = ``""``
 386   Default environment variables which test process uses for ``check-openmp``
 387   separated by space.  This can be used for individual targets (``check-ompt``,
 388   ``check-ompt-multiplex``, ``check-libarcher``, ``check-libomp`` and
 389   ``check-libomptarget-*``) too.  Note that each test still overrides
 390   environment variables if needed.  For example, to change barrier pattern to be
 391   used from default hyper barrier to hierarchical barrier, run:
 392
 393 .. code-block:: console
 394
 395   $ CHECK_OPENMP_ENV="KMP_PLAIN_BARRIER_PATTERN=hier,hier KMP_FORKJOIN_BARRIER_PATTERN=hier,hier KMP_REDUCTION_BARRIER_PATTERN=hier,hier" make check-openmp