| # |
| #//===----------------------------------------------------------------------===// |
| #// |
| #// The LLVM Compiler Infrastructure |
| #// |
| #// This file is dual licensed under the MIT and the University of Illinois Open |
| #// Source Licenses. See LICENSE.txt for details. |
| #// |
| #//===----------------------------------------------------------------------===// |
| # |
| |
| ========================================================== |
| How to Build the LLVM* OpenMP* Runtime Library using CMake |
| ========================================================== |
| |
| ==== Version of CMake required: v2.8.0 or above ==== |
| |
| ============================================ |
| How to call cmake initially, then repeatedly |
| ============================================ |
| - When calling cmake for the first time, all needed compiler options |
| must be specified on the command line. After this initial call to |
| cmake, the compiler definitions must not be included for further calls |
| to cmake. Other options can be specified on the command line multiple |
| times including all definitions in the Build options section below. |
| - Example of configuring, building, reconfiguring, rebuilding: |
| $ mkdir build |
| $ cd build |
| $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 .. # Initial configuration |
| $ make |
| ... |
| $ make clean |
| $ cmake -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug .. # Second configuration |
| $ make |
| ... |
| $ rm -rf * |
| $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=x86_64 .. # Third configuration |
| $ make |
| - Notice in the example how the compiler definitions are only specified |
| for an empty build directory, but other Build options are used at any time. |
| - The file CMakeCache.txt which is created after the first call to cmake |
| is a configuration file which holds all the values for the Build options. |
| These configuration values can be changed using a text editor to modify |
| CMakeCache.txt as opposed to using definitions on the command line. |
| - To have cmake create a particular type of build generator file simply |
| inlude the -G <Generator name> option: |
| $ cmake -G "Unix Makefiles" ... |
| You can see a list of generators cmake supports by executing cmake with |
| no arguments and a list will be printed. |
| |
| ===================== |
| Instructions to Build |
| ===================== |
| $ cd libomp_top_level/ [ directory with src/ , exports/ , tools/ , etc. ] |
| $ mkdir build |
| $ cd build |
| |
| [ Unix* Libraries ] |
| $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> .. |
| |
| [ Intel(R) Many Integrated Core Library (Intel(R) MIC Library) ] |
| $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DLIBOMP_ARCH=mic .. |
| |
| [ Windows Libraries ] |
| $ cmake -G <Generator Type> -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release .. |
| |
| $ make |
| $ make install |
| |
| ================== |
| Mac* Fat Libraries |
| ================== |
| On OS X* machines, it is possible to build universal (or fat) libraries which |
| include both i386 and x86_64 architecture objects in a |
| single archive. |
| $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' .. |
| $ make |
| There is also an option -DLIBOMP_OSX_ARCHITECTURES which can be set in case |
| this is an LLVM source tree build which will only set the libomp library |
| to a universal fat library and prevent having the entire llvm/clang build |
| produce universal binaries. |
| |
| =========== |
| Micro tests |
| =========== |
| After the library has been built, there are five optional microtests that |
| can be performed. Some will be skipped based upon the platform. |
| To run the tests, |
| $ make libomp-micro-tests |
| |
| ============= |
| CMake options |
| ============= |
| -DCMAKE_C_COMPILER=<C compiler name> |
| Specify the C compiler |
| |
| -DCMAKE_CXX_COMPILER=<C++ compiler name> |
| Specify the C++ compiler |
| |
| -DCMAKE_Fortran_COMPILER=<Fortran compiler name> |
| This option is only needed when -DLIBOMP_FORTRAN_MODULES is on. |
| So typically, a Fortran compiler is not needed during the build. |
| Specify the Fortran compiler |
| |
| -DCMAKE_ASM_MASM_COMPILER=[ml | ml64 ] |
| This option is Windows* Only |
| |
| -DLIBOMP_ARCH=i386|x86_64|arm|ppc64|ppc64le|aarch64|mic |
| The default for the option is chosen based on the probing the compiler for |
| architecture macros (e.g., is __x86_64__ predefined by compiler?). |
| |
| ==== First values listed are the default value ==== |
| -DLIBOMP_LIB_TYPE=normal|profile|stubs |
| Library type can be normal, profile, or stubs. |
| |
| -DCMAKE_BUILD_TYPE=Release|Debug|RelWithDebInfo |
| Build type can be Release, Debug, or RelWithDebInfo. |
| |
| -DLIBOMP_OMP_VERSION=45|40|30 |
| OpenMP version can be either 45, 40 or 30. |
| |
| -DLIBOMP_MIC_ARCH=knc|knf |
| This value is ignored if LIBOMP_ARCH != mic |
| Intel(R) MIC Architecture, can be knf or knc. |
| |
| -DLIBOMP_FORTRAN_MODULES=off|on |
| Should the Fortran modules be created (requires Fortran compiler) |
| |
| -DLIBOMP_USE_ADAPTIVE_LOCKS=on|off |
| Should adaptive (TSX-based) locks be included? |
| These are x86 specific. This feature is turned on by default |
| for i386 and x86_64. Otherwise, it is turned off. |
| |
| -DLIBOMP_USE_INTERNODE_ALIGNMENT=off|on |
| Should 4096-byte alignment be used for certain data structures? |
| This option is useful on multinode systems where a small CACHE_LINE |
| setting leads to false sharing. This option is off by default. |
| |
| -DLIBOMP_USE_VERSION_SYMBOLS=on|off |
| Should versioned symbols be used for building the library? |
| This option only makes sense for ELF based libraries where version |
| symbols are supported (Linux, some BSD* variants). It is off |
| by default for Windows and Mac, but on for other Unix based operating |
| systems. |
| |
| -DLIBOMP_ENABLE_SHARED=on|off |
| Shared library instead of static library? (Note: static libraries are not |
| supported on Windows). If LIBOMP_ENABLE_SHARED is off, then static OpenMP |
| libraries will be built instead of dynamic ones. |
| |
| -DLIBOMP_OMPT_SUPPORT=off|on |
| Should OMPT support be included in the build? (Not supported on Windows) |
| If LIBOMP_OMPT_SUPPORT is off, then both ompt_blame and ompt_trace are ignored. |
| |
| -DLIBOMP_OMPT_BLAME=on|off |
| Should OMPT blame functionality be included in the build? |
| |
| -DLIBOMP_OMPT_TRACE=on|off |
| Should OMPT trace functionality be included in the build? |
| |
| -DLIBOMP_STATS=off|on |
| Should include stats-gathering code be included in the build? |
| |
| -DLIBOMP_USE_DEBUGGER=off|on |
| Should the friendly debugger interface be included in the build? |
| |
| -DLIBOMP_USE_HWLOC=off|on |
| Should the Hwloc library be used for affinity? |
| This option is not supported on Windows. |
| http://www.open-mpi.org/projects/hwloc |
| |
| -DLIBOMP_HWLOC_INSTALL_DIR=/path/to/hwloc/install/dir |
| Default: /usr/local |
| This option is only used if LIBOMP_USE_HWLOC is on. |
| Specifies install location of Hwloc. The configuration system will look for |
| hwloc.h in ${LIBOMP_HWLOC_INSTALL_DIR}/include and the library in |
| ${LIBOMP_HWLOC_INSTALL_DIR}/lib. |
| |
| -DLIBOMP_LLVM_LIT_EXECUTABLE=/path/to/llvm-lit |
| Default: search in PATH |
| Specifiy full path to llvm-lit executable for running tests. |
| |
| -DOPENMP_LLVM_TOOLS_DIR=/path/to/built/llvm/tools |
| Default: search for tools in path |
| Additional path to search for LLVM tools needed by tests. |
| |
| ================================ |
| How to append flags to the build |
| ================================ |
| - These flags are *appended*. They do not |
| overwrite any of the preset flags. |
| -DLIBOMP_CPPFLAGS=<space-separated flags> -- Additional C preprocessor flags |
| -DLIBOMP_CFLAGS=<space-separated flags> -- Additional C compiler flags |
| -DLIBOMP_CXXFLAGS=<space-separated flags> -- Additional C++ compiler flags |
| -DLIBOMP_ASMFLAGS=<space-separated flags> -- Additional assembly flags |
| -DLIBOMP_LDFLAGS=<space-separated flags> -- Additional linker flags |
| -DLIBOMP_LIBFLAGS=<space-separated flags> -- Additional libraries to link |
| -DLIBOMP_FFLAGS=<space-separated flags> -- Additional Fortran compiler flags |
| |
| ======================= |
| Example usages of CMake |
| ======================= |
| ---- Typical usage ---- |
| cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc .. |
| cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. |
| cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. |
| |
| ---- With Various Options ---- |
| - Build the i386 Linux library using GCC* |
| cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 .. |
| |
| - Build the x86_64 debug Mac library using Clang* |
| cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug .. |
| |
| - Build the library (architecture determined by probing compiler) using the |
| Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create the fortran modules using |
| the Intel(R) Fortran Compiler. |
| cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on .. |
| |
| - Have CMake Find the C/C++ compiler, and specify additional flags for the C compiler, preprocessor, and C++ compiler. |
| cmake -DLIBOMP_CFLAGS='-specific-flag' -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' .. |
| |
| ---- Build the stubs library ---- |
| cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs .. |
| |
| ========= |
| Footnotes |
| ========= |
| [*] Other names and brands may be claimed as the property of others. |