This file explains how to install and use an experimental Prolog-based
coding rule checker for C++. The licencing terms of this software can
be found in file COPYING distributed with it.

This software is part of the GlobalGCC Project (http://www.ggcc.info).

This software has been tested on GNU/Linux systems only.

If you have any questions or suggestions, please write to
gmarpons@babel.ls.fi.upm.es.


Contents:

  1. Get the software from the public repository
  2. Install prerequisites
  3. Compile and install the software
  4. Basic usage


1. Get the software from the public repository

  You need Git (version 1.5.3 or later, see http://git.or.cz/) to get
  a copy of the software.

  The software is subdivided into two modules distributed separately:
  
    (a) GlobalGCC/codingrules, containing the Prolog code for
        analyzing C++ programs.
    (b) A modified version of GCC, with an added command-line option
        for extracting program information as Prolog facts.

  You can get module (a), GlobalGCC/codingrules, from our public Git
  repository executing:

  # git-clone git://abraham.ls.fi.upm.es/ggcc-codingrules.git

  This creates a directory 'ggcc-codingrules' containing a private
  copy of the repository. 

  Module (b) is a Git submodule of module (a), placed at directory
  'gcc'. For downloading module (b) you need to execute:

  # cd ggcc-codingrules && git-submodule init && git-submodule update

  Our public repository of GCC will be cloned into
  ggcc-codingrules/gcc. This may take a long time.

  Alternatively, you can get a standalone version of module (b):

  # git-clone git://abraham.ls.fi.upm.es/gcc-codingrules.git

  This can be useful if you are only interested in the functionality
  integrated into GCC, and you do not want to use the static analyzer
  provided in module (a), but in this case you will be on your own for
  compiling GCC.

  Our GCC Git repository was originally cloned from (and is
  periodically synced with) that in 

  http://git.infradead.org/gcc.git

  Thanks to those that created and maintain it!


2. Install prerequisites

  Dependencies are:

  2.1. Ciao Prolog
  2.2. Tools and libraries needed to compile GCC

2.1. Ciao Prolog

  Ciao Prolog is a GPL'd Prolog System that can be obtained at
 
  http://clip.dia.fi.upm.es/Software/Ciao/Beta/download.html		

  Alternatively, you can use the unofficial Debian/Ubuntu Ciao Prolog
  packages (i386) placed at

  http://abraham.ls.fi.upm.es/packages/

  Gutsy packages can also be run in Ubuntu Hardy Heron 8.04 and Ubuntu
  Intrepid Ibex 8.10. Necessary packages are ciao-prolog and
  ciao-prolog-libs. ciao-prolog-el is an Emacs development environment
  for Ciao Prolog.

  For instance, for Ubuntu Gutsy / Hardy / Intrepid you need only to
  add the following line in your /etc/apt/sources.list file, and use
  your preferred apt-based installation method:

  deb http://abraham.ls.fi.upm.es/packages/ubuntu-gutsy-i386/ ./		
    
2.2. Tools and libraries needed to compile GCC 

  The C++ compiler of the GNU Compiler Collection needs to be built,
  so look at

  http://gcc.gnu.org/install/prerequisites.html	

  for needed tools and libraries. In particular, make sure you have
  recent enough versions of GMP and MPFR libraries in your system
  (those in Ubuntu Intrepid Ibex 8.10 are up to date). Also 'flex' is
  needed.


3. Compile and install the software

  There are two steps involved in the process:

    3.1. Compile and install the modified version of GCC
    3.2. Compile the static checker with Ciao Prolog


3.1. Compile and install the modified version of GCC
   
  In the base directory of the GlobalGCC/codingrules distribution (see
  Sect. 1) there is a Makefile that can be used for configuring GCC
  for its compilation. In the aforementioned directory run:

  # make configure-gcc

  This command creates a directory 'obj' where GCC will be compiled
  in. Then, it calls 'configure' from there, with some default
  options, as the path where GCC will be installed or the paths where
  GMP and MPFR libraries are placed in the system. All these options
  can be modified with environment variables passed to the make
  command (see the Makefile for details).

  Only C and C++ compilers are built, with particular
  checking/debugging options. If different options are needed, you
  must rely on manual configuration of GCC:

  http://gcc.gnu.org/install/configure.html
    
  For manually compiling and installing GCC:

  # cd obj && make && make install

  By default, the compiler binaries will be placed at $HOME/local/bin.


3.2. Compile the static checker with Ciao Prolog

  If Ciao is correctly installed and their binaries accessible through
  the PATH environment variable, you only have to execute, from the
  base directory of the GlobalGCC/codingrules distribution
     
  # make bin/checkrules bin/localrules

  for generating the static analysis tool binary.


4. Basic usage

  To run the new GCC with coding rule compliance analysis you need to
  adapt your PATH to include the 'bin' directory under the base
  directory of the GlobalGCC/codingrules distribution. E.g., in bash,
  and supposing you have installed GlobalGCC/codingrules directly in
  your home, you need to do:

  # export PATH=$PATH:$HOME/ggcc-codingrules/bin

  You also need to define a new environment variable that contains the
  directory where you can install rule sets to check code
  against. In bash you need to write:

  #  export CHECKRULES_RULESETS_DIR=$HOME/ggcc-gmarpons/CodingRuleCheck/RuleSets/

  Then, you can pass to the executable 'checkrules' any command that
  (directly or indirectly) compiles C++ code with the new installed
  compiler, and activate the -fipa-codingrules flag. For instance, and
  supposing you have installed the new GCC in $HOME/local/bin (the
  default), you can write:

  # checkrules $HOME/local/bin/g++ -fipa-codingrules foo.cpp

  'checkrules' is going to process the information gathered by 'g++'
  and present some statistics about rule compliance at the end.

  Checking a C++ full project for compliance with coding rules is also
  possible using any building tool, such as 'make', simply doing

  # checkrules make

  All the instances of 'g++' created by 'make' are going to
  communicate with 'checkrules' to report rule compliance
  information. Obviously, you need to instruct 'make' to use the
  correct version of 'g++', and activate the -fipa-codingrules flag.

  As an example, here we show the steps followed to analyze the
  free software backup solution Bacula (http://www.bacula.org/).

  Firstly, download the source code:

  # wget http://downloads.sourceforge.net/bacula/bacula-2.2.8.tar.gz

  and extract it:

  # tar xvzf bacula-2.2.8.tar.gz

  Then, configure and compile the project (maybe you need to install
  some dependencies first):

  # cd bacula-2.2.8
  # ./configure --enable-client-only CC="$HOME/local/bin/gcc"    \
           CXX="$HOME/local/bin/g++ -fipa-codingrules"
  # checkrules make

  Maybe you have to replace $HOME/local/ by the actual path used for
  installing your development version of GCC (in Sect. 3.1).