397 lines · plain
1========================================2How to Build the LLVM* OpenMP* Libraries3========================================4This repository requires `CMake <http://www.cmake.org/>`_ v2.8.0 or later. LLVM5and Clang need a more recent version which also applies for in-tree builds. For6more information than available in this document please see7`LLVM's CMake documentation <https://llvm.org/docs/CMake.html>`_ and the8`official documentation <https://cmake.org/cmake/help/v2.8.0/cmake.html>`_.9 10.. contents::11 :local:12 13How to Call CMake Initially, then Repeatedly14============================================15- When calling CMake for the first time, all needed compiler options must be16 specified on the command line. After this initial call to CMake, the compiler17 definitions must not be included for further calls to CMake. Other options18 can be specified on the command line multiple times including all definitions19 in the build options section below.20- Example of configuring, building, reconfiguring, rebuilding:21 22 .. code-block:: console23 24 $ mkdir build25 $ cd build26 $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. # Initial configuration27 $ make28 ...29 $ make clean30 $ cmake -DCMAKE_BUILD_TYPE=Debug .. # Second configuration31 $ make32 ...33 $ rm -rf *34 $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. # Third configuration35 $ make36 37- Notice in the example how the compiler definitions are only specified for an38 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 is40 a configuration file which holds all values for the build options. These41 values can be changed using a text editor to modify ``CMakeCache.txt`` as42 opposed to using definitions on the command line.43- To have CMake create a particular type of build generator file simply include44 the ``-G <Generator name>`` option:45 46 .. code-block:: console47 48 $ cmake -G "Unix Makefiles" ...49 50 You can see a list of generators CMake supports by executing the cmake command51 with no arguments.52 53Instructions to Build54=====================55.. code-block:: console56 57 $ cd openmp_top_level/ [ this directory with libomptarget/, runtime/, etc. ]58 $ mkdir build59 $ cd build60 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 $ make68 $ make install69 70CMake Options71=============72Builds with CMake can be customized by means of options as already seen above.73One possibility is to pass them via the command line:74 75.. code-block:: console76 77 $ cmake -DOPTION=<value> path/to/source78 79.. note:: The first value listed is the respective default for that option.80 81Generic Options82---------------83For full documentation consult the CMake manual or execute84``cmake --help-variable VARIABLE_NAME`` to get information about a specific85variable.86 87**CMAKE_BUILD_TYPE** = ``Release|Debug|RelWithDebInfo``88 Build type can be ``Release``, ``Debug``, or ``RelWithDebInfo`` which chooses89 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 when99 **LIBOMP_FORTRAN_MODULES** is ``ON`` (see below). So typically, a Fortran100 compiler is not needed during the build.101 102**CMAKE_ASM_MASM_COMPILER** = ``ml|ml64``103 This option is only relevant for Windows*.104 105Options for all Libraries106-------------------------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 for116 building.117 118**OPENMP_TEST_CXX_COMPILER** = ``${CMAKE_CXX_COMPILER}``119 Compiler to use for testing. Defaults to the compiler that was also used for120 building.121 122**OPENMP_TEST_Fortran_COMPILER** = ``${CMAKE_Fortran_COMPILER}``123 Compiler to use for testing. Defaults to the compiler that was also used for124 building.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 default131 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 default135 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 default139 is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.140 141Options for ``libomp``142----------------------143 144**LIBOMP_ARCH** = ``aarch64|aarch64_32|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 for146 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) to150 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 sense157 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`` for159 other Unix based operating systems.160 161**LIBOMP_ENABLE_SHARED** = ``ON|OFF``162 Build a shared library. If this option is ``OFF``, static OpenMP libraries163 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 172macOS* Fat Libraries173""""""""""""""""""""174On macOS* machines, it is possible to build universal (or fat) libraries which175include both i386 and x86_64 architecture objects in a single archive.176 177.. code-block:: console178 179 $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' ..180 $ make181 182There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case183this is an LLVM source tree build. It will only apply for the ``libomp`` library184avoids having the entire LLVM/Clang build produce universal binaries.185 186Optional Features187"""""""""""""""""188 189**LIBOMP_USE_ADAPTIVE_LOCKS** = ``ON|OFF``190 Include adaptive locks, based on Intel(R) Transactional Synchronization191 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 on196 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 if206 **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/>`_ for216 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 for220 ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in221 ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``. The default is ``/usr/local``.222 This option is only used if **LIBOMP_USE_HWLOC** is ``ON``.223 224Additional Compiler Flags225"""""""""""""""""""""""""226 227These 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 247Options for ``libomptarget``248----------------------------249 250An installed LLVM package is a prerequisite for building ``libomptarget``251library. 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** or255- as a standalone project build that uses a pre-installed LLVM package.256 In this mode one has to make sure that the default CMake257 ``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 testing261 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 267Options 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 time272 optimization of the OMP runtime and application code. This option is enabled273 by default if the build system determines that `CMAKE_C_COMPILER` is able to274 compile and link the library.275 276**LIBOMPTARGET_NVPTX_CUDA_COMPILER** = ``""``277 Location of a CUDA compiler capable of emitting LLVM bitcode. Currently only278 the Clang compiler is supported. This is only used when building the CUDA LLVM279 bitcode offloading device RTL. If unspecified, either the Clang from the build280 itself is used (i.e. an in-tree build with LLVM_ENABLE_PROJECTS including281 clang), or the Clang compiler that the build uses as C compiler282 (CMAKE_C_COMPILER; only if it is Clang). The latter is common for a283 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 only287 used when building the CUDA LLVM bitcode offloading device RTL. If288 unspecified, either the llvm-link in that same directory as289 LIBOMPTARGET_NVPTX_CUDA_COMPILER is used, or the llvm-link from the290 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 to294 produce any binary. Instead, this is used to overcome the input compiler295 checks done by NVCC. E.g. if using a default host compiler that is not296 compatible with NVCC, this option can be use to pass to NVCC a valid compiler297 to avoid the error.298 299 **LIBOMPTARGET_NVPTX_COMPUTE_CAPABILITIES** = ``35``300 List of CUDA compute capabilities that should be supported by the NVPTX301 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`` and309 ``make check-libomptarget-*`` are affected. For example, use310 ``LIBOMPTARGET_LIT_ARGS="-j4"`` to force ``lit`` to start only four parallel311 jobs instead of by default the number of threads in the system.312 313Example Usages of CMake314=======================315 316Typical Invocations317-------------------318 319.. code-block:: console320 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 325Advanced Builds with Various Options326------------------------------------327 328- Build the i386 Linux* library using GCC*329 330 .. code-block:: console331 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:: console337 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 the341 Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create Fortran342 modules with the Intel(R) Fortran Compiler.343 344 .. code-block:: console345 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 the349 preprocessor and C++ compiler.350 351 .. code-blocks:: console352 353 $ cmake -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' ..354 355- Build the stubs library356 357 .. code-blocks:: console358 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 365How to Run Tests366================367 368There 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-ompt-omptest`` (ompt omptest tests under tools/omptest/tests)373- ``check-libarcher`` (libarcher tests under tools/archer/tests)374- ``check-libomp`` (libomp tests under runtime/test. This includes check-ompt tests too)375- ``check-libomptarget-*`` (libomptarget tests for specific target under libomptarget/test)376- ``check-libomptarget`` (all check-libomptarget-* tests)377- ``check-openmp`` (combination of all above tests excluding duplicates)378 379For example, to run all available tests, use ``make check-openmp``.380 381Options for Tests382------------------383Tests use lit framework.384See `lit documentation <https://llvm.org/docs/CommandGuide/lit.html>`_ for lit options.385 386**CHECK_OPENMP_ENV** = ``""``387 Default environment variables which test process uses for ``check-openmp``388 separated by space. This can be used for individual targets (``check-ompt``,389 ``check-ompt-multiplex``, ``check-libarcher``, ``check-libomp`` and390 ``check-libomptarget-*``) too. Note that each test still overrides391 environment variables if needed. For example, to change barrier pattern to be392 used from default hyper barrier to hierarchical barrier, run:393 394.. code-block:: console395 396 $ CHECK_OPENMP_ENV="KMP_PLAIN_BARRIER_PATTERN=hier,hier KMP_FORKJOIN_BARRIER_PATTERN=hier,hier KMP_REDUCTION_BARRIER_PATTERN=hier,hier" make check-openmp397