###########################
 clang-coral C/C++ README 
###########################

This file provides a basic description and instructions on how to use the clang-coral C/C++ compiler and runtime libraries and execute applications built with it.

#######################################
 Selecting the right compiler package.
#######################################

We provide packages for different operating system flavors, CUDA versions, and GPU compute capabilities. We also include an x86_64 package. The names of the packages aim at being self-explanatory. E.g.

clang-coral-0.2-pwr8-rhel7.2-cuda7.5-sm3.7.tar.bz2

...refers to a power 8 (pwr8) architecture, RedHat 7.2 OS, version 7.5 of the CUDA toolkit, and is prepared to generated binaries for GPU whose CUDA compute capability is 3.7.

We currently have two distinct versions of the compiler:

0.1 - refers to the compiler implementation based on the github port that had the first clang OpenMP support.
0.2 - refers to the compiler that is based on the latest (or a few days old) upstream clang and is the one that is currently being actively developed.

##################
 Package contents
##################

bin - contains all the clang and llvm tools, including the compiler main driver: clang and clang++

include - contains the clang and llvm header files useful if using clang and llvm as a library. It also contains the LLVM official C++ standard library header files.

lib - contains that clang and llvm libraries as well as the LLVM official C++ standard library.

omprtl - contains the omp.h include file.
omprtl/lib - contains the OpenMP runtime libraries.

tests - contains a set of tests that the current implementation was tested with. To run the tests, run 'make' in this folder.

########################
 Define the environment
########################

The compiler has to be able to locate the OpenMP include files and libraries. Therefore, a few environment variables are recommended to be set:

C_INCLUDE_PATH=<package location>/omprtl
CPLUS_INCLUDE_PATH=<package location>/omprtl
LIBRARY_PATH=<package location>/omprtl/lib
LD_LIBRARY_PATH=<package location>/omprtl/lib:/usr/local/cuda/lib64

Alternatively the user can explicitly define the library and include path by using the -I and -L compiler options.

#####################
 Using the compiler
#####################

To use the compiler the user should select the right driver for C (clang) or C++ (clang++).

To compile code with OpenMP support:

> clang -fopenmp a.c -o a.bin

To compile code with OpenMP support including NVIDIA GPU offload support:

> clang -fopenmp -fopenmp-targets=nvptx64-nvidia-cuda a.c -o a.bin

Note that the CUDA compute capability is not required to be specified, as the compiler is only prepared to deal with the single compute capability specified in the package name.

Separate compilation is supported as long as no static libraries are used. The compiler is not prepared to look for host and device code in static libraries. Dynamic libraries are supported.

By the default the system gcc C++ standard library is used by clang, unless the user explicitly request the LLVM C++ standard library. To use the LLVM C++ library one can use:

> clang -fopenmp -fopenmp-targets=nvptx64-nvidia-cuda -stdlib=libc++ -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc  a.c -o a.bin

###########################
 Executing the application
###########################

As long as the right environment is defined, namely LD_LIBRARY_PATH pointing to <package location>/omprtl/lib:/usr/local/cuda/lib64, the binary generated by the compiler can be executed as usually:

> ./a.bin

or by using the user favorite dispatching tools.

If the user desires to use the LLVM C++ standard library, <package location>/lib should also be present in LD_LIBRARY_PATH.