Mercurial > hg > CbC > CbC_llvm

comparison openmp/README.rst @ 150:1d019706d866

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LLVM10
author anatofuz
date Thu, 13 Feb 2020 15:10:13 +0900
parents
children 0572611fdcc8
comparison
equal deleted inserted replaced
147:c2174574ed3a 150:1d019706d866
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.