2014-08-05 17:32:28 +08:00
|
|
|
#
|
|
|
|
|
#//===----------------------------------------------------------------------===//
|
|
|
|
|
#//
|
|
|
|
|
#// 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.
|
|
|
|
|
#//
|
|
|
|
|
#//===----------------------------------------------------------------------===//
|
|
|
|
|
#
|
|
|
|
|
|
2015-05-12 20:52:43 +08:00
|
|
|
How to Build the LLVM* OpenMP* Runtime Library using CMake
|
|
|
|
|
===========================================
|
2014-08-05 17:32:28 +08:00
|
|
|
|
|
|
|
|
---- 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++ -Darch=32 .. # Initial configuration
|
|
|
|
|
$ make all common
|
|
|
|
|
...
|
|
|
|
|
$ make clean
|
|
|
|
|
$ cmake -Darch=32e -DCMAKE_BUILD_TYPE=Debug .. # Second configuration
|
|
|
|
|
$ make all common
|
|
|
|
|
...
|
|
|
|
|
$ rm -rf *
|
|
|
|
|
$ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -Darch=32e .. # Third configuration
|
|
|
|
|
$ make all common
|
|
|
|
|
- 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
|
|
|
|
|
|
|
|
|
|
[ Linux* , Mac* Libraries ]
|
|
|
|
|
$ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
|
|
|
|
|
|
|
|
|
|
[ Intel(R) Many Integrated Core Library (Intel(R) MIC Library) ]
|
2015-01-16 21:05:23 +08:00
|
|
|
$ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -Darch=mic ..
|
2014-08-05 17:32:28 +08:00
|
|
|
|
|
|
|
|
[ Windows Libraries ]
|
|
|
|
|
$ cmake -G "Unix Makefiles" -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release ..
|
|
|
|
|
|
|
|
|
|
$ make all common
|
|
|
|
|
|
|
|
|
|
=================
|
|
|
|
|
Mac* Fat Libraries
|
|
|
|
|
=================
|
|
|
|
|
On OS X* machines, it is possible to build universal (or fat) libraries which
|
|
|
|
|
include both IA-32 architecture and Intel(R) 64 architecture objects in a
|
|
|
|
|
single archive; just build the 32 and 32e libraries separately:
|
|
|
|
|
$ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -Darch=32 ..
|
|
|
|
|
$ make
|
|
|
|
|
$ cmake -Darch=32e ..
|
|
|
|
|
$ make
|
|
|
|
|
then invoke make again with a special argument as follows:
|
|
|
|
|
$ make fat
|
|
|
|
|
- The fat target is only available for the arch=32e configuration.
|
|
|
|
|
- The fat libraries will be put in exports/mac_32e/lib while the "thin" libraries
|
|
|
|
|
will be in exports/mac_32e/lib.thin and exports/mac_32/lib.thin
|
|
|
|
|
|
|
|
|
|
================
|
|
|
|
|
Compiler options
|
|
|
|
|
================
|
|
|
|
|
-DCMAKE_C_COMPILER=<C compiler name>
|
|
|
|
|
-DCMAKE_CXX_COMPILER=<C++ compiler name>
|
|
|
|
|
|
|
|
|
|
-DCMAKE_Fortran_COMPILER=<Fortran compiler name>
|
|
|
|
|
Unix* systems (Optional as compiler is default):
|
|
|
|
|
This option is only needed when -Dcreate_fortran_modules is true
|
|
|
|
|
|
|
|
|
|
-DCMAKE_ASM_MASM_COMPILER=[ml | ml64 ]
|
|
|
|
|
This option is Windows* Only
|
|
|
|
|
|
|
|
|
|
=============
|
|
|
|
|
Build options
|
|
|
|
|
=============
|
|
|
|
|
|
|
|
|
|
==========================
|
|
|
|
|
==== Operating System ====
|
|
|
|
|
==========================
|
2015-01-16 21:05:23 +08:00
|
|
|
-Dos=lin|mac|win
|
|
|
|
|
* Operating system can be lin (Linux*), mac (Mac*), or win (Windows*).
|
2014-08-05 17:32:28 +08:00
|
|
|
If not specified, cmake will try to determine your current operating system.
|
|
|
|
|
|
|
|
|
|
======================
|
|
|
|
|
==== Architecture ====
|
|
|
|
|
======================
|
2015-05-12 20:52:43 +08:00
|
|
|
-Darch=32|32e|arm|ppc64|ppc64le|aarch64|mic
|
2014-08-07 18:12:54 +08:00
|
|
|
* Architecture can be 32 (IA-32 architecture), 32e (Intel(R) 64 architecture),
|
2015-05-12 20:52:43 +08:00
|
|
|
arm (ARM architecture), aarch64 (ARMv8 architecture), ppc64 (PPC64 architecture),
|
|
|
|
|
or ppc64le (little endian PPC64 architecture).
|
|
|
|
|
* This option, by default is chosen based on the probing the compiler for
|
|
|
|
|
architecture macros (e.g., is __x86_64__ predefined by compiler?).
|
2014-08-05 17:32:28 +08:00
|
|
|
|
|
|
|
|
---- First values listed are the default value ----
|
|
|
|
|
-Dlib_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.
|
|
|
|
|
See below for interaction when -DUSE_BUILDPL_RULES is on.
|
|
|
|
|
|
|
|
|
|
-Dversion=5|4
|
|
|
|
|
libiomp5 version can be 5 or 4.
|
|
|
|
|
|
|
|
|
|
-Domp_version=40|30
|
|
|
|
|
OpenMP version can be either 40 or 30.
|
|
|
|
|
|
|
|
|
|
-Dmic_arch=knc|knf
|
I apologise in advance for the size of this check-in. At Intel we do
understand that this is not friendly, and are working to change our
internal code-development to make it easier to make development
features available more frequently and in finer (more functional)
chunks. Unfortunately we haven't got that in place yet, and unpicking
this into multiple separate check-ins would be non-trivial, so please
bear with me on this one. We should be better in the future.
Apologies over, what do we have here?
GGC 4.9 compatibility
--------------------
* We have implemented the new entrypoints used by code compiled by GCC
4.9 to implement the same functionality in gcc 4.8. Therefore code
compiled with gcc 4.9 that used to work will continue to do so.
However, there are some other new entrypoints (associated with task
cancellation) which are not implemented. Therefore user code compiled
by gcc 4.9 that uses these new features will not link against the LLVM
runtime. (It remains unclear how to handle those entrypoints, since
the GCC interface has potentially unpleasant performance implications
for join barriers even when cancellation is not used)
--- new parallel entry points ---
new entry points that aren't OpenMP 4.0 related
These are implemented fully :-
GOMP_parallel_loop_dynamic()
GOMP_parallel_loop_guided()
GOMP_parallel_loop_runtime()
GOMP_parallel_loop_static()
GOMP_parallel_sections()
GOMP_parallel()
--- cancellation entry points ---
Currently, these only give a runtime error if OMP_CANCELLATION is true
because our plain barriers don't check for cancellation while waiting
GOMP_barrier_cancel()
GOMP_cancel()
GOMP_cancellation_point()
GOMP_loop_end_cancel()
GOMP_sections_end_cancel()
--- taskgroup entry points ---
These are implemented fully.
GOMP_taskgroup_start()
GOMP_taskgroup_end()
--- target entry points ---
These are empty (as they are in libgomp)
GOMP_target()
GOMP_target_data()
GOMP_target_end_data()
GOMP_target_update()
GOMP_teams()
Improvements in Barriers and Fork/Join
--------------------------------------
* Barrier and fork/join code is now in its own file (which makes it
easier to understand and modify).
* Wait/release code is now templated and in its own file; suspend/resume code is also templated
* There's a new, hierarchical, barrier, which exploits the
cache-hierarchy of the Intel(r) Xeon Phi(tm) coprocessor to improve
fork/join and barrier performance.
***BEWARE*** the new source files have *not* been added to the legacy
Cmake build system. If you want to use that fixes wil be required.
Statistics Collection Code
--------------------------
* New code has been added to collect application statistics (if this
is enabled at library compile time; by default it is not). The
statistics code itself is generally useful, the lightweight timing
code uses the X86 rdtsc instruction, so will require changes for other
architectures.
The intent of this code is not for users to tune their codes but
rather
1) For timing code-paths inside the runtime
2) For gathering general properties of OpenMP codes to focus attention
on which OpenMP features are most used.
Nested Hot Teams
----------------
* The runtime now maintains more state to reduce the overhead of
creating and destroying inner parallel teams. This improves the
performance of code that repeatedly uses nested parallelism with the
same resource allocation. Set the new KMP_HOT_TEAMS_MAX_LEVEL
envirable to a depth to enable this (and, of course, OMP_NESTED=true
to enable nested parallelism at all).
Improved Intel(r) VTune(Tm) Amplifier support
---------------------------------------------
* The runtime provides additional information to Vtune via the
itt_notify interface to allow it to display better OpenMP specific
analyses of load-imbalance.
Support for OpenMP Composite Statements
---------------------------------------
* Implement new entrypoints required by some of the OpenMP 4.1
composite statements.
Improved ifdefs
---------------
* More separation of concepts ("Does this platform do X?") from
platforms ("Are we compiling for platform Y?"), which should simplify
future porting.
ScaleMP* contribution
---------------------
Stack padding to improve the performance in their environment where
cross-node coherency is managed at the page level.
Redesign of wait and release code
---------------------------------
The code is simplified and performance improved.
Bug Fixes
---------
*Fixes for Windows multiple processor groups.
*Fix Fortran module build on Linux: offload attribute added.
*Fix entry names for distribute-parallel-loop construct to be consistent with the compiler codegen.
*Fix an inconsistent error message for KMP_PLACE_THREADS environment variable.
llvm-svn: 219214
2014-10-08 00:25:50 +08:00
|
|
|
Intel(R) MIC Architecture, can be knf or knc.
|
2014-08-05 17:32:28 +08:00
|
|
|
This value is ignored if os != mic
|
|
|
|
|
|
|
|
|
|
-Dcreate_fortran_modules=off|on
|
|
|
|
|
Should the Fortran modules be created (requires Fortran compiler)
|
|
|
|
|
|
|
|
|
|
-Dstats=off|on
|
|
|
|
|
Should include stats-gathering code?
|
|
|
|
|
|
2015-05-12 20:52:43 +08:00
|
|
|
-Dompt_support=off|on
|
|
|
|
|
Should OMPT support be turned on?
|
|
|
|
|
If ompt_support is off, then both ompt_blame and ompt_trace are ignored.
|
|
|
|
|
|
|
|
|
|
-Dompt_blame=on|off
|
|
|
|
|
should OMPT blame functionality be turned on?
|
|
|
|
|
|
|
|
|
|
-Dompt_trace=on|off
|
|
|
|
|
should OMPT trace functionality be turned on?
|
|
|
|
|
|
2014-08-05 17:32:28 +08:00
|
|
|
=====================
|
|
|
|
|
==== Micro tests ====
|
|
|
|
|
=====================
|
2015-05-12 20:52:43 +08:00
|
|
|
After the library has been built, there are five optional microtests that
|
|
|
|
|
can be performed. Some will be skipped based upon the platform.
|
2014-08-05 17:32:28 +08:00
|
|
|
These tests can be turned on (default) or off with the following options:
|
|
|
|
|
-Dtest_touch=on|off -- Should the touch test be done?
|
|
|
|
|
-Dtest_relo=on|off -- Should the position independent code test be done?
|
|
|
|
|
-Dtest_execstack=on|off -- Should the stack be checked for executability?
|
2015-05-12 20:52:43 +08:00
|
|
|
-Dtest_instr=on|off -- Should the Intel(R) MIC Libraries be checked
|
2014-08-05 17:32:28 +08:00
|
|
|
for correct instruction set?
|
|
|
|
|
-Dtest_deps=on|off -- Should libiomp5's dependencies be checked?
|
|
|
|
|
-Dtests=off|on -- Should any of the above tests be done?
|
2015-05-12 20:52:43 +08:00
|
|
|
If -Dtests=on is specified, the user can then call:
|
|
|
|
|
$ make libiomp-micro-tests
|
|
|
|
|
which runs the tests.
|
2014-08-05 17:32:28 +08:00
|
|
|
|
|
|
|
|
============================================
|
|
|
|
|
==== How to append flags to compilation ====
|
|
|
|
|
============================================
|
|
|
|
|
- These flags are *appended*. They do not
|
|
|
|
|
overwrite any of the preset flags.
|
2015-05-12 20:52:43 +08:00
|
|
|
-DLIBIOMP_CPPFLAGS=<space-separated flags> -- Additional C Preprocessor flags
|
2014-08-05 17:32:28 +08:00
|
|
|
(typically additional -Ddef=val flags)
|
2015-05-12 20:52:43 +08:00
|
|
|
-DLIBIOMP_CFLAGS=<space-separated flags> -- Additional C compiler flags
|
|
|
|
|
-DLIBIOMP_CXXFLAGS=<space-separated flags> -- Additional C++ compiler flags
|
|
|
|
|
-DLIBIOMP_ASMFLAGS=<space-separated flags> -- Additional assembly flags
|
|
|
|
|
-DLIBIOMP_LDFLAGS=<space-separated flags> -- Additional linker flags
|
|
|
|
|
-DLIBIOMP_LIBFLAGS=<space-separated flags> -- Additional libraries to link
|
2014-08-05 17:32:28 +08:00
|
|
|
to during link phase
|
2015-05-12 20:52:43 +08:00
|
|
|
-DLIBIOMP_FFLAGS=<space-separated flags> -- Additional Fortran compiler flags
|
2014-08-05 17:32:28 +08:00
|
|
|
|
|
|
|
|
===================================
|
|
|
|
|
==== Feature Based Compilation ====
|
|
|
|
|
===================================
|
|
|
|
|
-DUSE_BUILDPL_RULES=false|true
|
|
|
|
|
Should the build imitate build.pl's build process.
|
|
|
|
|
When this is true, the Unix* Release builds will build libiomp5
|
|
|
|
|
with -O2 and -g flags activated (same as RelWithDebInfo). Then,
|
|
|
|
|
the debug info is stripped out of the library and put into libiomp5.dbg
|
|
|
|
|
This is done for interaction with Intel(R) Parallel Amplifier.
|
|
|
|
|
|
|
|
|
|
-DUSE_ADAPTIVE_LOCKS=true|false
|
|
|
|
|
Should adaptive (TSX-based) locks be included?
|
|
|
|
|
These are x86 specific. This feature is turned on by default
|
|
|
|
|
for IA-32 architecture and Intel(R) 64 architecture.
|
|
|
|
|
Otherwise, it is turned off.
|
|
|
|
|
|
2015-01-16 21:05:23 +08:00
|
|
|
-DUSE_INTERNODE_ALIGNMENT=false|true
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
-DUSE_VERSION_SYMBOLS=true|false
|
|
|
|
|
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.
|
|
|
|
|
|
2014-08-05 17:32:28 +08:00
|
|
|
-DUSE_PREDEFINED_LINKER_FLAGS=true|false
|
|
|
|
|
Should the predefined linker flags in CommonFlags.cmake be included
|
|
|
|
|
in the link command? This is true by default and should work for
|
|
|
|
|
Linux*, Mac*, and Windows*. The --version-script flag on Unix* based
|
|
|
|
|
operating systems will be included regardless.
|
|
|
|
|
|
|
|
|
|
========================
|
|
|
|
|
Examples 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 ----
|
2015-05-12 20:52:43 +08:00
|
|
|
- Build the 32 bit Linux library using GCC*
|
2014-08-05 17:32:28 +08:00
|
|
|
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -Dos=lin -Darch=32 ..
|
2015-05-12 20:52:43 +08:00
|
|
|
|
|
|
|
|
- Build the 32 bit debug Mac library using Clang*
|
2014-08-05 17:32:28 +08:00
|
|
|
cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -Dos=mac -Darch=32 -DCMAKE_BUILD_TYPE=Debug ..
|
2015-05-12 20:52:43 +08:00
|
|
|
|
|
|
|
|
- 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, enabling the libiomp-micro-tests target and using similar rules that build.pl
|
|
|
|
|
would use to build the library.
|
2014-08-05 17:32:28 +08:00
|
|
|
cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -Dtests=on -Dcreate_fortran_modules=on -DUSE_BUILDPL_RULES=on ..
|
|
|
|
|
|
2015-05-12 20:52:43 +08:00
|
|
|
- Have CMake Find the C/C++ compiler, and specify additional flags for the C compiler, preprocessor, and C++ compiler.
|
|
|
|
|
cmake -DLIBIOMP_CFLAGS='Werror' -DLIBIOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBIOMP_CXXFLAGS='-Werror -Wsign-compare' ..
|
|
|
|
|
|
|
|
|
|
---- Build the stubs library ----
|
2014-08-05 17:32:28 +08:00
|
|
|
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -Dlib_type=stubs ..
|
|
|
|
|
|
|
|
|
|
=========
|
|
|
|
|
Footnotes
|
|
|
|
|
=========
|
|
|
|
|
[*] Other names and brands may be claimed as the property of others.
|