******************************* ENCODE ********************************
* A simple "AN encoder" based on the LLVM compiler framework and the  *
* CLANG compiler front-end.                                           *
*                                                                     *
* Created: 2015-03-03                                                 *
* Author: Norman Rink                                                 *
*         TU Dresden                                                  *
*         Center for Advancing Electronics Dresden (cfaed)            *
*         Chair for Compiler Construction                             *
*         Georg-Schumann-Str. 7A                                      *
*         01062 Dresden, GERMANY                                      *
***********************************************************************



*** Licensing and acknowledgements: ***

LLVM and CLANG are subject to the University of Illinois Open Source
License. Please refer to the LLVM project's main web page at

  http://llvm.org

and also to the LICENSE.TXT files in your LLVM and CLANG source trees
respectively.

This work was inspired by discussions and code reviews with Dmitry
Kuvayskiy (TU Dresden), and the encoded operations implemented in
'anlib.c' were taken directly from D. Kuvayskiy's "AN-transfomer".



*** Description: ***

TODO: TO BE WRITTEN



*** Requirements: ***

The AN encoder must be built against a modified versions of LLVM/CLANG
3.5.1. These versions of LLVM/CLANG are provided by the 'intrinsics'
branches of the following repositories:

  https://nrink@bitbucket.org/nrink/llvm-351.git (for LLVM)

  https://nrink@bitbucket.org/nrink/clang-351.git (for CLANG)

Make sure you run the command

  git fetch && git checkout intrinsics

in both repositories after cloning them.

You must have built both LLVM and CLANG 3.5.1 before you can proceed to
building the AN encoder. Please refer to the LLVM documentation at

  http://llvm.org/docs

If you are new to LLVM, you may find the following pages useful:

  http://llvm.org/docs/GettingStarted.html
  http://llvm.org/docs/CMake.html

Note that the AN encoder is configured to be built with cmake. You
should therefore build LLVM and CLANG with cmake too. Building the AN
encoder against an LLVM/CLANG build that has not been obtained by using
cmake has not been tested and is unlikely to work.



*** Building the encoder: ***

The AN encoder project comes with a build script in

  <TOP LEVEL SOURCE DIR>/encode/bin/build.sh

To build the AN encoder, execute the build.sh script from within the
directory where you want the AN encoder to be created - subsequently
refered to as the 'build directory'. This will generate a directory
structure below the build directory, which includes the following:

  a) the AN encoder's main executable, named "encode"
  b) runtime resources for the AN encoder
  c) the script "apply-an.sh" (see below for details)
  d) C-source files for testing the AN encoder

Before the build.sh script can be run, two environment variables must
be set:

  1) ENCODE_DIR
        This must be set to the top level source directory of the
        AN encoder code, i.e. the directory into which you have cloned
        the AN encoder repository.

  2) LLVM_BUILD_DIR
        This must be set to the top level directory of your LLVM 3.5.1
        build that you have generated as part fo the requirements for
        building the AN encoder (please refer to the previous section).

Note that if these environment variables are not set, the build.sh
script will assume default values for these variables, which are
unlikely to be correct in your environment.



*** Running the encoder: ***

After build.sh has successfully completed, the following executables
will exist:

  1) <'build directory'>/encode/src/encode
        This is the binary file that applies the AN encoder to its
        input. It takes as input an LLVM bitcode file, and outputs
        a modified bitcode file which operates on coded data.
  2) <'build directory'>/encode/apply-an.sh
        This script takes as input a C-source file and produces two
        executables from it: The first executable has been instrumented
        with a cycle counter. This serves as the reference point for
        performance measurements. The second executable is the
        AN-encoded version of the first one. It has also been
        instrumented with the same cycle counter.

For running the apply-an.sh script the following environment variables must be set:

  1) ENCODE_BINARY_DIR
        This should be set to the directory in which the "encode"
        binary has been created, which should be
        <'build directory'>/encode/src.
  2) ENCODE_RUNTIME_DIR
        This should be set to <'build directory'>/encode/runtime.
  3) LLVM_BUILD_DIR
        This should be set to the top level directory under which the
        LLVM and CLANG 3.5.1 builds have been created.