
0. CONTENTS OF THIS FILE
===============================================================================

1. BEFORE YOU START
   * Prerequisites
   * Order of building and installing

2. BUILDING AND INSTALLING
   * libcci
   * ccc
   * ccie
   * ccc-scripts

3. USAGE INSTRUCTIONS
   * Setting up your environment for compiler wrapping
   * Extracting call information
   * Constructing a call graph
   * Getting help


1. BEFORE YOU START
===============================================================================


* Prerequisites
-------------------------------------------------------------------------------

The entire system was developed and tested on Ubuntu Linux. Versions
8.10 and up of the Ubuntu distribution will work. Older versions might work as
well, but have not been tested. A recent Debian distribution will most likely
be just as good, although this has not been tested.

In order to be able to build libcci, ccc and ccie, you need the packages listed
here (and their dependencies):

- gcc-4.3. Versions 4.1 and 4.2 are likely to work as well, but have
  not been tested since the beginning of the project.

- g++-4.3. Versions 4.1 and 4.2 are likely to work as well, but have
  not been tested since the beginning of the project.

- flex-2.5.4a. This is the old version of flex. This package is called flex-old
  on Ubuntu. The system does not compile with the new version of flex.

- bison-2.4.1. Other versions have not been tested.

- libsqlite3-dev-3.6.16. Other versions have not been tested.

All of the packages above are readily available from the Ubuntu package
repository.

NOTE: libcci and ccc compile without problems using gcc/g++ version 4.4.
However, ccie does not compile using g++-4.4.


* Order of building and installing
-------------------------------------------------------------------------------

When building and installing the different components you should bear in mind
that there are some dependencies between the components. This requires that
you build and install the libcci component before you attempt to build the ccie
and ccc systems. The ccc-scripts component does not have any dependencies and
can be installed at any time.

If you simply stick to the order that is presented in this document, you will
be fine.


2. BUILDING AND INSTALLING
===============================================================================

This section guides you through the process of building and installing libcci,
ccc, ccie and ccc-scripts. Note that you need ALL of these components installed
on your system in order to be able to construct call graphs.

* libcci
-------------------------------------------------------------------------------

Extract the package to a directory of your choice:
> tar -xzf libcci.tar.gz

Then, change into the newly created directory:
> cd libcci

Once there, you first need to configure the source tree for your system:
> ./configure

If running configure gives you any errors, fix them, rerun configure and then
come back here.
Now you are ready to build the libcci library:
> make

When make finishes you need to install the library on your system.
AS ROOT, do:
> make install

Finally, since you just installed a shared library you need to run ldconfig.
That way, the ccc and ccie systems will be able to find and use it.
AS ROOT, do:
> ldconfig


* ccc
-------------------------------------------------------------------------------

Extract the package to a directory of your choice:
> tar -xzf ccc.tar.gz

Then, change into the newly created directory:
> cd ccc

Once there, you first need to configure the source tree for your system:
> ./configure

If running configure gives you any errors, fix them, rerun configure and then
come back here.
Now you are ready to build the ccc executable:
> make

When make finishes all you need to do is install the executable on your system.
AS ROOT, do:
> make install


* ccie
-------------------------------------------------------------------------------

Extract the package to a directory of your choice:
> tar -xzf ccie-stack.tar.gz

Then, change into the newly created directory:
> cd ccie-stack

Once there, you first need to configure the source tree for your system:
> ./configure

If running configure gives you any errors, fix them, rerun configure and then
come back here.
Now you are ready to build the ccie executable:
> make

When make finishes all you need to do is install the executable on your system.
Change into the install directory:
> cd install

Run configure to make sure everything is setup properly:
> ./configure

Finally, install the executable on your system.
AS ROOT, do:
> make install


* ccc-scripts
-------------------------------------------------------------------------------

Extract the package to a directory of your choice:
> tar -xzf ccc-scripts.tar.gz

Then, change into the newly created directory:
> cd ccc-scripts

Once there, you first need to configure the source tree for your system:
> ./configure

When configure finishes all you need to do is install the scripts on your
system.
AS ROOT, do:
> make install


3. USAGE INSTRUCTIONS
===============================================================================


* Setting up your environment for compiler wrapping
-------------------------------------------------------------------------------

To make the system practically usable, you will need to utilize the compiler
wrapping scripts you just installed. To setup your environment to use these
scripts, navigate to the root of the code base that you wish to generate call
graphs for (we will assume that the root of your code base is called 'src'):
> cd src

At the root of your code base, issue:
> ccc-init

This will copy a small set of files to your code base. These files will be used
to wrap the compiler (and the associated tools).

Please take a look at the ccc-config file that has just been copied using your
favourite text editor. This file allows you to set a number of directories, but
the only setting that will probably be of interest is the CCC_CCIE_ARGS
variable. This variable allows you to set the arguments that will be passed to
ccie during information extraction. The example values of CCC_CCIE_ARGS in the
ccc-config file are likely to be the most interesting values, so you might want
to examine them.

Once the contents of ccc-config is to your liking (the default is probably
fine), you need to source the file so the variables are exported to your
current shell:
> . ccc-config

Your environment is now setup for compiler wrapping. This means that whenever
the gcc, g++ or c++ compiler is called from your current shell (or a descendent
shell), the wrapper scripts will be invoked and call information will be
extracted from the source files that are being compiled.

If at any point in time you wish to restore your environment, simply issue:
> . ccc-unconfig

This will undo any changes that were made to your environment when sourcing the
ccc-config file.


* Extracting call information
-------------------------------------------------------------------------------

Now that your environment is setup for compiler wrapping, you can invoke make
(or something similar) on your code base, just as you normally would:
> make

This will effectively compile your code base and extract the needed call
information. Since this will first compile and then extract call information
from each translation unit, this process will take somewhat longer than a
regular build.

Just like make will build one or more targets, the extraction system will
create one or more corresponding call information archives: For each binary
target (i.e., each library or executable) exactly one corresponding call
information archive will be created.


* Constructing a call graph
-------------------------------------------------------------------------------

When call information extraction is finished, you will want to generate one or
more call graphs from the extracted information. The provided scripts allow you
to generate a call graph corresponding to one binary target (i.e., a library or
an executable).

To discover for what targets you can generate a call graph, you can use the
ccc-run command:
> ccc-run -l

This will list all available call information archive files that exist in the
current directory and any of its subdirectories. So, say that you just applied
the system to the source code of GNU bison
(http://www.gnu.org/software/bison/), then the above command will yield
something like this:
./a.out.ccia
./src/bison.ccia
./lib/libbison.a.ccia
./lib/liby.a.ccia

As you can see four targets were produced. The second and the third archive
files represent the bison executable and the libbison library, respectively. If
you would now want to produce a call graph for the bison executable, viewable
using Tulip (http://tulip.labri.fr/), and write the output to the bison.tlp
file, you would issue:
> ccc-run ./src/bison.ccia -f tulip -o bison.tlp

This will write a bison.tlp file to the current directory, which you can then
directly load into Tulip.

To generate a SolidSX compatible graph file, you would issue:
> ccc-run ./src/bison.ccia -f sqlite -o bison.db

To generate a Graphviz compatible graph file, you would issue:
> ccc-run ./src/bison.ccia -f dot -o bison.dot


* Getting help
-------------------------------------------------------------------------------

The various programs (ccc, ccie, ccc-run) all have their own set of command
line arguments. To learn what these arguments are and what they do, use the
following commands:

For help with ccc, issue:
> ccc --help

For help with ccie, issue:
> ccie --help

For help with ccc-run, issue:
> ccc-run --help

