|
| 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 <http://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_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 | +Options for ``libomp`` |
| 134 | +---------------------- |
| 135 | + |
| 136 | +**LIBOMP_ARCH** = ``aarch64|arm|i386|mic|mips|mips64|ppc64|ppc64le|x86_64`` |
| 137 | + The default value for this option is chosen based on probing the compiler for |
| 138 | + architecture macros (e.g., is ``__x86_64__`` predefined by compiler?). |
| 139 | + |
| 140 | +**LIBOMP_MIC_ARCH** = ``knc|knf`` |
| 141 | + Intel(R) Many Integrated Core Architecture (Intel(R) MIC Architecture) to |
| 142 | + build for. This value is ignored if **LIBOMP_ARCH** does not equal ``mic``. |
| 143 | + |
| 144 | +**LIBOMP_OMP_VERSION** = ``50|45|40|30`` |
| 145 | + OpenMP version to build for. Older versions will disable certain |
| 146 | + functionality and entry points. |
| 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 | + |
| 168 | +macOS* Fat Libraries |
| 169 | +"""""""""""""""""" |
| 170 | +On macOS* machines, it is possible to build universal (or fat) libraries which |
| 171 | +include 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 | +
|
| 178 | +There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case |
| 179 | +this is an LLVM source tree build. It will only apply for the ``libomp`` library |
| 180 | +avoids having the entire LLVM/Clang build produce universal binaries. |
| 181 | + |
| 182 | +Optional 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** = ``OFF|ON`` |
| 195 | + Include support for the OpenMP Tools Interface (OMPT). |
| 196 | + |
| 197 | +**LIBOMP_OMPT_OPTIONAL** = ``ON|OFF`` |
| 198 | + Include support for optional OMPT functionality. This option is ignored if |
| 199 | + **LIBOMP_OMPT_SUPPORT** is ``OFF``. |
| 200 | + |
| 201 | +**LIBOMP_STATS** = ``OFF|ON`` |
| 202 | + Include stats-gathering code. |
| 203 | + |
| 204 | +**LIBOMP_USE_DEBUGGER** = ``OFF|ON`` |
| 205 | + Include the friendly debugger interface. |
| 206 | + |
| 207 | +**LIBOMP_USE_HWLOC** = ``OFF|ON`` |
| 208 | + Use `OpenMPI's hwloc library <https://www.open-mpi.org/projects/hwloc/>`_ for |
| 209 | + topology detection and affinity. |
| 210 | + |
| 211 | +**LIBOMP_HWLOC_INSTALL_DIR** = ``/path/to/hwloc/install/dir`` |
| 212 | + Specify install location of hwloc. The configuration system will look for |
| 213 | + ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in |
| 214 | + ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``. The default is ``/usr/local``. |
| 215 | + This option is only used if **LIBOMP_USE_HWLOC** is ``ON``. |
| 216 | + |
| 217 | +Additional Compiler Flags |
| 218 | +""""""""""""""""""""""""" |
| 219 | + |
| 220 | +These flags are **appended**, they do not overwrite any of the preset flags. |
| 221 | + |
| 222 | +**LIBOMP_CPPFLAGS** = <space-separated flags> |
| 223 | + Additional C preprocessor flags. |
| 224 | + |
| 225 | +**LIBOMP_CFLAGS** = <space-separated flags> |
| 226 | + Additional C compiler 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 | + |
| 243 | +Options 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 | + |
| 254 | +Example Usages of CMake |
| 255 | +======================= |
| 256 | + |
| 257 | +Typical Invocations |
| 258 | +------------------- |
| 259 | + |
| 260 | +.. code-block:: console |
| 261 | +
|
| 262 | + $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. |
| 263 | + $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. |
| 264 | + $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc .. |
| 265 | +
|
| 266 | +Advanced Builds with Various Options |
| 267 | +------------------------------------ |
| 268 | + |
| 269 | +- Build the i386 Linux* library using GCC* |
| 270 | + |
| 271 | + .. code-block:: console |
| 272 | +
|
| 273 | + $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 .. |
| 274 | +
|
| 275 | +- Build the x86_64 debug Mac library using Clang* |
| 276 | + |
| 277 | + .. code-block:: console |
| 278 | +
|
| 279 | + $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug .. |
| 280 | +
|
| 281 | +- Build the library (architecture determined by probing compiler) using the |
| 282 | + Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create Fortran |
| 283 | + modules with the Intel(R) Fortran Compiler. |
| 284 | + |
| 285 | + .. code-block:: console |
| 286 | +
|
| 287 | + $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on .. |
| 288 | +
|
| 289 | +- Have CMake find the C/C++ compiler and specify additional flags for the C |
| 290 | + compiler, preprocessor, and C++ compiler. |
| 291 | + |
| 292 | + .. code-blocks:: console |
| 293 | + |
| 294 | + $ cmake -DLIBOMP_CFLAGS='-specific-flag' -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' .. |
| 295 | + |
| 296 | +- Build the stubs library |
| 297 | + |
| 298 | + .. code-blocks:: console |
| 299 | + |
| 300 | + $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs .. |
| 301 | + |
| 302 | +**Footnotes** |
| 303 | + |
| 304 | +.. [*] Other names and brands may be claimed as the property of others. |
0 commit comments