libcilkrts/README

Intel(R) Cilk(TM) Plus Runtime Library

Index:
1. BUILDING WITH AUTOMAKE
2. BUILDING WITH CMAKE
3. INSTALLING TO VXWORKS
4. USING
5. DOXYGEN DOCUMENTATION
6. QUESTIONS OR BUGS
7. CONTRIBUTIONS

#
#  1. BUILDING WITH AUTOMAKE:
#

To distribute applications that use the Intel Cilk Plus language
extensions to non-development systems, you need to build the Intel
Cilk Plus runtime library and distribute it with your application.

To build the libcilkrts.so runtime library component, you need the
autoconf and automake packages, which are available through your
favorite package manager.  You also need a C/C++ compiler that
supports the Intel Cilk Plus language extensions, since the runtime
uses Intel Cilk Plus features internally.  Use either the Intel(R)
C++ Compiler (icc command) v12.1 or later, or in GCC 4.9 or later
(gcc command).

Once you have the necessary prerequisites installed, you can use the
following commands to create the library:

% libtoolize
% aclocal
% automake --add-missing
% autoconf
% ./configure
% make
% make install

This will produce the libcilkrts.so shared object.  To install the
library in a custom location, set the prefix while running the
configure script:

% ./configure --prefix=/your/path/to/lib

#
#  2. BUILDING WITH CMAKE:
#

To distribute applications that use the Intel Cilk Plus language
extensions to non-development systems, you need to build the Intel
Cilk Plus runtime library and distribute it with your application.
This instruction describes the build process using CMake*, which
supports Linux*, Windows*, and OS X*.  It is fine to use this process
to build a Linux library, but it is highly recommended to use the
more mature build process described above when building on Linux.

You need the CMake tool and a C/C++ compiler that supports the Intel
Cilk Plus language extensions, and the requirements for each operating
systems are:

Common:
    CMake 3.0.0 or later
    Make tools such as make (Linux, OS X) or nmake (Windows)
Linux:
    GCC* 4.9.2 or later, or Intel(R) C++ Compiler v12.1 or later
Windows:
    Intel C++ Compiler v12.1 or later
    Visual Studio* 2010 or later
OS X:
    Cilk-enabled branch of Clang*/LLVM* (http://cilkplus.github.io),
    or Intel C++ Compiler v12.1 or later

The common steps to build the libraries are 1) invoke cmake with
appropriate options, 2) invoke a make tool available on the system.
The following examples show build processes on OS X and Windows.

OS X:
    % mkdir ./build && cd ./build
    % cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
            -DCMAKE_INSTALL_PREFIX=./install ..
    % make && make install

Windows:
    % mkdir .\build && cd .\build
    % cmake -G "NMake Makefiles" -DCMAKE_C_COMPILER=icl \
            -DCMAKE_CXX_COMPILER=icl -DCMAKE_INSTALL_PREFIX=.\install ..
    % nmake && nmake install

#
#  3. INSTALLING TO VXWORKS OS
#

For Windows host, run VxWorks_Install.bat.
For Linux host, run VxWorks_Install.sh.

You may need to give environment variable WIND_BASE to indicate VxWorks
installation path.

Create a VSB project, and you will see a layer named "CILKPLUS_KERNEL".
Enable it and build the project.

Create a VIP project with ICC and add component INCLUDE_CILKPLUS, then you
will get support of Intel Cilk Plus features in VxWorks.

#
#  4. USING:
#

The Intel(R) C++ Compiler will automatically try to bring in the
Intel Cilk Plus runtime in any program that uses the relevant
features.  GCC and Clang requires an explicit compiler option,
-fcilkplus, to enable Intel Cilk Plus language extensions.
For example,

% gcc -fcilkplus -o foo.exe foo.c
% clang -fcilkplus -o foo.exe foo.c 

Older GCC versions (e.g., 4.8 cilkplus branch) requires explicit linking
of both the library and its dependencies (libpthread, libdl).
For example:

% gcc foo.c -lcilkrts -lpthread -ldl

#
#  5. DOXYGEN DOCUMENTATION:
#

The library source has Doxygen markup.  Generate HTML documentation
based on the markup by changing directory into runtime and running:

% doxygen doxygen.cfg

#
#  6. QUESTIONS OR BUGS:
#

Issues with the Intel Cilk Plus runtime can be addressed in the Intel
Cilk Plus forums:
http://software.intel.com/en-us/forums/intel-cilk-plus/

#
#  7. CONTRIBUTIONS:
#

The Intel Cilk Plus runtime library is dual licensed. The upstream copy
of the library is maintained via the BSD-licensed version available at:
http://cilkplus.org/

Changes to the Intel Cilk Plus runtime are welcome and should be
contributed to the upstream version via http://cilkplus.org/.

Thanks to Tobias Burnus for showing us the magic to make gcc and g++
automatically include the Cilk Plus runtime.

Thanks to Eric Olson for sharing his patch for Raspberry Pi* with us.

Thanks to Rainer Orth for submitting patches for exception handling and
enabling Cilk Plus on the SPARC* architecture.

------------------------
Intel and Cilk are trademarks of Intel Corporation in the U.S. and/or
other countries.

*Other names and brands may be claimed as the property of others.