Introduction
============

clang-triage is a bot which does, broadly, the following:

* Periodically try to checkout a newer version of llvm and clang

  * If found, build and execute clang for all given test cases

  * Whether new llvm/clang were found or not, generate a HTML report

* When not building clang or executing test cases, see if there are
  currently failing test cases which have not been reduced; if so, try
  to reduce them using CReduce. On failure, use a builtin dumber
  (fast, but produces very terse results) reduction algorithm.

The idea is to have a large number of malformed inputs which have
previously caused crashes or otherwise exercise weird code paths in
clang or LLVM. The test verdict only depends on whether clang crashed
on the input or not; there is no functionality to do anything with the
object file, if any, produced. A good way to produce large numbers of
such cases is by running afl-fuzz.

In principle there is no reason why this could not be easily modified
to test other LLVM frontends besides clang, non-LLVM compilers or even
non-compilers.


Prerequisites
=============

* python 3 (3.4.2 tested)
* python3-psycopg2 (2.5.4 tested)
* postgresql database (9.4 tested)
* git
* cmake and ninja (the build system)
* creduce
  * also, creduce's dependencies
* python3-pystache (0.5.4 tested)
* timeout from GNU coreutils
* pbzip2, unless you change config.py to use plain bzip2


Setup
=====

1. Edit config.py to match your setup. TOP and REPORT_DIR are probably
   the most important variables to customize. If you do not have
   pbzip2, change BZIP2_COMMAND to 'bzip2'.

2. git checkout llvm and tools/clang from the repository you wish to
   follow to LLVM_SRC as specified in config.

3. Configure LLVM for cmake/ninja build in BUILD.

  a) Use something like

       cmake ../llvm.src -DCMAKE_BUILD_TYPE="RelWithDebInfo" \
           -DLLVM_ENABLE_ASSERTIONS=ON -DCLANG_ENABLE_STATIC_ANALYZER=OFF \
	   -DCLANG_ENABLE_ARCMT=OFF -GNinja

  b) You may also build it (no need to install) if you wish - otherwise
     clang-triage will do that for you.

4. Create a database with the name in DB_NAME and grant yourself the
   rights to it.

  a) For example: as postgres (the postgresql superuser), run psql and
     issue the following SQL statements (assuming your username is
     joeuser and your postgres is configured, as it is at least in
     Debian, to match Unix usernames to postgres usernames):

       CREATE ROLE clang_triage;
       CREATE USER joeuser IN ROLE clang_triage;
       CREATE DATABASE clang_triage OWNER clang_triage;

  b) Alternatively, if you already have a PostgreSQL user and database
     creation rights, you may just run the command

       createdb clang_triage (or whatever you have set DB_NAME to)

5. Populate the database with the cases by running

     ./import_cases.py /path/to/cases

   where /path/to/cases contains your test cases. All files under the
   directory will be imported, recursively; the filenames do not
   matter. If you wonder where to get cases, get an existing
   all_cases.tar.bz2 from somewhere or run afl-fuzz (or some similar
   one) to get new ones.

6. Now you should be ready to run the bot: run clang_triage.py from the
   clang-triage source directory.