pooo#+TITLE: Archer
Please see LICENSE for usage terms.
Archer is a data race detector for OpenMP programs.
Archer combines static and dynamic techniques to identify data races in large OpenMP applications, leading to low runtime and memory overheads, while still offering high accuracy and precision. It builds on open-source tools infrastructure such as LLVM and ThreadSanitizer to provide portability.
To compile Archer you need an host GCC version >= 4.7.
Archer has been developed under LLVM 3.5 with OpenMP support (for more information go to http://clang-omp.github.io).
First obtain Archer, e.g. from Github (https://github.com/soarlab/Archer):
git clone git@github.com:soarlab/Archer.git Archer
Then, build Archer by running install.sh
:
./install.sh --prefix=llvm_install_path [default: --prefix=/usr]
The installation script will create a folder called LLVM at the same level of the Archer directory and install LLVM to llvm_install_path.
In case your GCC is not installed in a standard path you need to specify the GCC toolchain path for LLVM/Clang using the flag –gcc-toolchain-path:
./install.sh --prefix=llvm_install_path --gcc-toolchain-path=gcc_toolchain_path
Once the installation completes, you need to setup your environement to allow Archer to work correctly.
Please set the following path variables:
export PATH=${LLVM_INSTALL}/bin:${LLVM_INSTALL}/local/archer/bin:\${PATH}"
export LD_LIBRARY_PATH=${LLVM_INSTALL}/bin:${LLVM_INSTALL}/lib/intelomprt:${LLVM_INSTALL}/local/archer/lib:\${LD_LIBRARY_PATH}"
To make the environment permanent add the previous lines or equivalents to your shell start-up script such as "~/.bashrc".
WARNING:
During the installation process you may see an error like the following:
CMake Error: install(EXPORT "LLVMExports" ...) includes target "opt" which requires target "Polly" that is not in the export set.
CMake Error: install(EXPORT "LLVMExports" ...) includes target "bugpoint" which requires target "Polly" that is not in the export set.
It is an error related to the CMake configuration process of Polly. It does not affect your installation. Future versions of Archer will upgrade Polly to the latest version avoiding this problem.
Archer provides a command to compile your programs with Clang/LLVM OpenMP and hide all the mechanics necessary to detect data races automatically in your OpenMP programs.
This Archer command is called clang-archer, and this can be used as a drop-in replacement of your compiler command (e.g., clang, gcc, etc.).
The following are some of the examples of how one can integrate clang-archer into his/her build system.
clang-archer example.c -L/path/to/openmp/runtime -lOMPRT -o example
In your Makefile, set the following variables:
CC = clang-archer
LDFLAGS = -L/path/to/openmp/runtime -lOMPRT
In your Makefile, set the following variables:
CC = mpicc -cc=clang-archer
...
LDFLAGS = -L/path/to/openmp/runtime -lOMPRT
Running the following command:
clang-archer --help
shows the options available with clang-archer.
usage: clang-archer [-h] [-v] [-d] [--log] [-db] [-CC [CC]] [-USE_MPI]
[-MPICC [MPICC]] [-OPT [OPT]] [-LINK [LINK]] [-DIS [DIS]]
[-LIB [LIB]] [-PLUGIN_LIB [PLUGIN_LIB]]
[-OPENMP_INCLUDE [OPENMP_INCLUDE]] [-g]
[-O0 | -O1 | -O2 | -O3 | -Os | -Oz] [-fopenmp] [-liomp5]
[-c] [-o [O]]
Compile your program with Archer support, a data race detector for OpenMP programs.
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-d, --debug Print the compiling commands
--log Keep intermediate logs
-db, --disable-blacklisting
Disable static analysis and apply ThreadSanitizer
instrumentation to the entire program
-CC [CC] Change the program used to compile and link the
programs
-USE_MPI Link against MPI libraries
-MPICC [MPICC] Change the program used to compile and link the MPI
programs
-OPT [OPT] Change the program used to optmize the programs
-LINK [LINK] Change the program used to link the byte code files
-DIS [DIS] Change the program used to disassemble the byte code
files
-LIB [LIB] Set the path where to find Archer libraries
-PLUGIN_LIB [PLUGIN_LIB]
Set the path where to find Archer Plugin libraries
-OPENMP_INCLUDE [OPENMP_INCLUDE]
Set the path where to find OpenMP headers
-g If the debugging flag is not present in the
compilation command it will be added by default
-O0 The optimization flags will be forced to '-O0'
optimization level for analysis purposes
-O1
-O2
-O3
-Os
-Oz
-fopenmp OpenMP flag
-liomp5 OpenMP library
-c Only run preprocess, compile, and assemble steps
-o [O] Output filename