1======================================== 2How to Build the LLVM* OpenMP* Libraries 3======================================== 4This repository requires `CMake <http://www.cmake.org/>`_ v2.8.0 or later. LLVM 5and Clang need a more recent version which also applies for in-tree builds. For 6more 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 13How 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 53Instructions 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 70CMake Options 71============= 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:: console 76 77 $ cmake -DOPTION=<value> path/to/source 78 79.. note:: The first value listed is the respective default for that option. 80 81Generic Options 82--------------- 83For full documentation consult the CMake manual or execute 84``cmake --help-variable VARIABLE_NAME`` to get information about a specific 85variable. 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 105Options 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_LLVM_TOOLS_DIR** = ``/path/to/built/llvm/tools`` 123 Additional path to search for LLVM tools needed by tests. 124 125**OPENMP_LLVM_LIT_EXECUTABLE** = ``/path/to/llvm-lit`` 126 Specify full path to ``llvm-lit`` executable for running tests. The default 127 is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**. 128 129**OPENMP_FILECHECK_EXECUTABLE** = ``/path/to/FileCheck`` 130 Specify full path to ``FileCheck`` executable for running tests. The default 131 is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**. 132 133**OPENMP_NOT_EXECUTABLE** = ``/path/to/not`` 134 Specify full path to ``not`` executable for running tests. The default 135 is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**. 136 137Options for ``libomp`` 138---------------------- 139 140**LIBOMP_ARCH** = ``aarch64|arm|i386|mic|mips|mips64|ppc64|ppc64le|x86_64|riscv64`` 141 The default value for this option is chosen based on probing the compiler for 142 architecture macros (e.g., is ``__x86_64__`` predefined by compiler?). 143 144**LIBOMP_MIC_ARCH** = ``knc|knf`` 145 Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture) to 146 build for. This value is ignored if **LIBOMP_ARCH** does not equal ``mic``. 147 148**LIBOMP_LIB_TYPE** = ``normal|profile|stubs`` 149 Library type can be ``normal``, ``profile``, or ``stubs``. 150 151**LIBOMP_USE_VERSION_SYMBOLS** = ``ON|OFF`` 152 Use versioned symbols for building the library. This option only makes sense 153 for ELF based libraries where version symbols are supported (Linux*, some BSD* 154 variants). It is ``OFF`` by default for Windows* and macOS*, but ``ON`` for 155 other Unix based operating systems. 156 157**LIBOMP_ENABLE_SHARED** = ``ON|OFF`` 158 Build a shared library. If this option is ``OFF``, static OpenMP libraries 159 will be built instead of dynamic ones. 160 161 .. note:: 162 163 Static libraries are not supported on Windows*. 164 165**LIBOMP_FORTRAN_MODULES** = ``OFF|ON`` 166 Create the Fortran modules (requires Fortran compiler). 167 168macOS* Fat Libraries 169"""""""""""""""""""" 170On macOS* machines, it is possible to build universal (or fat) libraries which 171include both i386 and x86_64 architecture objects in a single archive. 172 173.. code-block:: console 174 175 $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' .. 176 $ make 177 178There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case 179this is an LLVM source tree build. It will only apply for the ``libomp`` library 180avoids having the entire LLVM/Clang build produce universal binaries. 181 182Optional Features 183""""""""""""""""" 184 185**LIBOMP_USE_ADAPTIVE_LOCKS** = ``ON|OFF`` 186 Include adaptive locks, based on Intel(R) Transactional Synchronization 187 Extensions (Intel(R) TSX). This feature is x86 specific and turned ``ON`` 188 by default for IA-32 architecture and Intel(R) 64 architecture. 189 190**LIBOMP_USE_INTERNODE_ALIGNMENT** = ``OFF|ON`` 191 Align certain data structures on 4096-byte. This option is useful on 192 multi-node systems where a small ``CACHE_LINE`` setting leads to false sharing. 193 194**LIBOMP_OMPT_SUPPORT** = ``ON|OFF`` 195 Include support for the OpenMP Tools Interface (OMPT). 196 This option is supported and ``ON`` by default for x86, x86_64, AArch64, 197 PPC64 and RISCV64 on Linux* and macOS*. 198 This option is ``OFF`` if this feature is not supported for the platform. 199 200**LIBOMP_OMPT_OPTIONAL** = ``ON|OFF`` 201 Include support for optional OMPT functionality. This option is ignored if 202 **LIBOMP_OMPT_SUPPORT** is ``OFF``. 203 204**LIBOMP_STATS** = ``OFF|ON`` 205 Include stats-gathering code. 206 207**LIBOMP_USE_DEBUGGER** = ``OFF|ON`` 208 Include the friendly debugger interface. 209 210**LIBOMP_USE_HWLOC** = ``OFF|ON`` 211 Use `OpenMPI's hwloc library <https://www.open-mpi.org/projects/hwloc/>`_ for 212 topology detection and affinity. 213 214**LIBOMP_HWLOC_INSTALL_DIR** = ``/path/to/hwloc/install/dir`` 215 Specify install location of hwloc. The configuration system will look for 216 ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in 217 ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``. The default is ``/usr/local``. 218 This option is only used if **LIBOMP_USE_HWLOC** is ``ON``. 219 220Additional Compiler Flags 221""""""""""""""""""""""""" 222 223These flags are **appended**, they do not overwrite any of the preset flags. 224 225**LIBOMP_CPPFLAGS** = <space-separated flags> 226 Additional C preprocessor flags. 227 228**LIBOMP_CXXFLAGS** = <space-separated flags> 229 Additional C++ compiler flags. 230 231**LIBOMP_ASMFLAGS** = <space-separated flags> 232 Additional assembler flags. 233 234**LIBOMP_LDFLAGS** = <space-separated flags> 235 Additional linker flags. 236 237**LIBOMP_LIBFLAGS** = <space-separated flags> 238 Additional libraries to link. 239 240**LIBOMP_FFLAGS** = <space-separated flags> 241 Additional Fortran compiler flags. 242 243Options for ``libomptarget`` 244---------------------------- 245 246**LIBOMPTARGET_OPENMP_HEADER_FOLDER** = ``""`` 247 Path of the folder that contains ``omp.h``. This is required for testing 248 out-of-tree builds. 249 250**LIBOMPTARGET_OPENMP_HOST_RTL_FOLDER** = ``""`` 251 Path of the folder that contains ``libomp.so``. This is required for testing 252 out-of-tree builds. 253 254Options for ``NVPTX device RTL`` 255-------------------------------- 256 257**LIBOMPTARGET_NVPTX_ENABLE_BCLIB** = ``ON|OFF`` 258 Enable CUDA LLVM bitcode offloading device RTL. This is used for link time 259 optimization of the OMP runtime and application code. This option is enabled 260 by default if the build system determines that `CMAKE_C_COMPILER` is able to 261 compile and link the library. 262 263**LIBOMPTARGET_NVPTX_CUDA_COMPILER** = ``""`` 264 Location of a CUDA compiler capable of emitting LLVM bitcode. Currently only 265 the Clang compiler is supported. This is only used when building the CUDA LLVM 266 bitcode offloading device RTL. If unspecified and the CMake C compiler is 267 Clang, then Clang is used. 268 269**LIBOMPTARGET_NVPTX_BC_LINKER** = ``""`` 270 Location of a linker capable of linking LLVM bitcode objects. This is only 271 used when building the CUDA LLVM bitcode offloading device RTL. If unspecified 272 and the CMake C compiler is Clang and there exists a llvm-link binary in the 273 directory containing Clang, then this llvm-link binary is used. 274 275**LIBOMPTARGET_NVPTX_ALTERNATE_HOST_COMPILER** = ``""`` 276 Host compiler to use with NVCC. This compiler is not going to be used to 277 produce any binary. Instead, this is used to overcome the input compiler 278 checks done by NVCC. E.g. if using a default host compiler that is not 279 compatible with NVCC, this option can be use to pass to NVCC a valid compiler 280 to avoid the error. 281 282 **LIBOMPTARGET_NVPTX_COMPUTE_CAPABILITIES** = ``35`` 283 List of CUDA compute capabilities that should be supported by the NVPTX 284 device RTL. E.g. for compute capabilities 6.0 and 7.0, the option "60,70" 285 should be used. Compute capability 3.5 is the minimum required. 286 287 **LIBOMPTARGET_NVPTX_DEBUG** = ``OFF|ON`` 288 Enable printing of debug messages from the NVPTX device RTL. 289 290Example Usages of CMake 291======================= 292 293Typical Invocations 294------------------- 295 296.. code-block:: console 297 298 $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. 299 $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. 300 $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc .. 301 302Advanced Builds with Various Options 303------------------------------------ 304 305- Build the i386 Linux* library using GCC* 306 307 .. code-block:: console 308 309 $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 .. 310 311- Build the x86_64 debug Mac library using Clang* 312 313 .. code-block:: console 314 315 $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug .. 316 317- Build the library (architecture determined by probing compiler) using the 318 Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create Fortran 319 modules with the Intel(R) Fortran Compiler. 320 321 .. code-block:: console 322 323 $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on .. 324 325- Have CMake find the C/C++ compiler and specify additional flags for the 326 preprocessor and C++ compiler. 327 328 .. code-blocks:: console 329 330 $ cmake -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' .. 331 332- Build the stubs library 333 334 .. code-blocks:: console 335 336 $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs .. 337 338**Footnotes** 339 340.. [*] Other names and brands may be claimed as the property of others. 341