Merge branch 'addmainunit3-altlink-sharedstmt' into addmainunit3-altlink-sharedstmt...
[lldb.git] / openmp / README.rst
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 <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
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 **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
137 Options 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
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** = ``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
220 Additional Compiler Flags
221 """""""""""""""""""""""""
222
223 These 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
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 Options 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
290 Example Usages of CMake
291 =======================
292
293 Typical 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
302 Advanced 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.