Quick Start

Clone LLVM.

The project was started on LLVM release 3.0, it might or might not be forward compatible.

git clone http://llvm.org/git/llvm.git
cd llvm
git checkout release_30

Clone Clang.

This guide will use my mirror of Clang, which contains modifications specific to using CFCSS in the context of Fiasco.OC—if your project doesn't use __attribute__((init_priority(X))) you might do alright with upstream Clang, but I'm not testing that case.

Inside the llvm directory:

cd tools
git clone https://github.com/hermannloose/clang.git
cd clang
git checkout init-priority-mods

---

Note: it appears that Clang 3.3 received fixes ensuring proper handling of __attribute__((init_priority(X))), so

cd tools
git clone http://llvm.org/git/clang.git
cd clang
git checkout release_33

might do the job. Make sure to use the same branch in the LLVM repository in this case.

Build & install LLVM.

This follows their Getting Started guide.

Gotcha: $OBJ_ROOT and $SRC_ROOT have to be absolute paths. (It's written right there, but I know at least one person who missed it the first time …)

cd $OBJ_ROOT
$SRC_ROOT/configure --enable-assertions --enable-jit --enable-targets=host-only \
    --enable-bindings=none --prefix=$INSTALL_DIR
make -j6
make install

Clone CFCSS.

git clone https://github.com/hermannloose/cfcss.git

Build CFCSS.

cd $OBJ_ROOT
$SRC_ROOT/configure --with-llvmsrc=$LLVM_SRC_ROOT --with-llvmobj=$LLVM_OBJ_ROOT \
    --prefix=$INSTALL_DIR
make

wherein $OBJ_ROOT, $SRC_ROOT and $INSTALL_DIR refer to the CFCSS-related directories and $LLVM_SRC_ROOT and $LLVM_OBJ_ROOT are the directories used in previously building LLVM. You will want your CXXFLAGS to contain -std=c++11 since CFCSS uses the new integer distributions contained in <random> and probably the auto keyword in one or two places.

Instrument code with CFCSS.

See Running a pass with opt for reference.

The second line of optimization passes cleans up after CFCSS instrumentation.

opt -load $OJB_ROOT/Debug+Asserts/lib/CFCSS.so -instrument-blocks < test.bc > test-instrumented.bc
opt -simplifycfg -mem2reg < test-instrumented.bc > test-optimized.bc

This is ideally done on a single bitcode module containing your whole library or executable. Instrumenting single translation units will work, but CFCSS cannot currently provide control-flow checking across module borders. Calls to functions contained in other translation units, regardless of whether they are instrumented or not, will be ignored by CFCSS.

See CFCSS in action.

The CFCSS pintool (requires Intel® Pin) provides a way of injecting control-flow faults that CFCSS is designed to detect.