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