Vera++ - documentation

# Vera++ Community Edition - manual

Copyright 2006-2007 Maciej Sobczak

Introduction
Compiling
Running
Index of available rules
Index of available transformations
Script API

Introduction

Vera++ is a programmable tool for verification, analysis and transformation of C++ source code.

The main usage scenarios that are foreseen for Vera++ are:

- Ensure that the source code complies with the given coding standards and conventions.
- Provide source code metrics and statistics.
- Perform automated transformations of the source code, which can range from pretty-printing to diagnostics to fault injection and advanced testing.

The main design idea of Vera++ is to create a generic engine that will be able to parse the C++ code and present it in the form of collections of various objects to user provided scripts that will define the concrete actions to be executed.

Currently the following object collections are provided:

- Collection of source file names.
- Collection of source lines for each file.
- Collection of identified tokens in each file.

Note: It is foreseen that future versions of Vera++ will provide also the semantic view on the code.

The most important feature of Vera++ is that all activities other than code parsing are defined by scripts. This means that Vera++ is flexible and extensible.

For example, compliance with coding standards can be expressed in terms of rules, each being defined by a separate script. The scripts can access all collections listed above and perform actions related to the given rule. The user can ask to run any given script or some defined set of scripts in a single program execution.

As a simple example, a coding convention that limits the length of the source line can be implemented as a script that traverses the collection of files and the collection of source lines and checks whether each source line fits within the given limits. A report can be generated for each non-conforming line of code so that the user gets a clear information about where the problem is located.

All existing rules present their reports in the format that is compatible with regular compiler's output, so that it is easy to integrate Vera++ with the existing build framework.

Similarly, automated transformation procedures are implemented as separate scripts that scan the above collections and produce another source files according to their algorithms. A simple example of such transformation might be a script that removes empty lines from source code.

The Tcl programming language is currently supported for scripts that run within Vera++.

Compiling Vera++

Vera++ is implemented in C++ and depends on the Boost libraries.

Note that it is not necessary to build or install Boost before compiling Vera++, but the full source tree of Boost has to be available at the time Vera++ itself is compiled. Please note that some ready to use Boost packages do not provide the complete source tree and the full source package will have to be used instead.

The `src/Make.common` file contains paths and variables used during the compilation process. The following variables need to be set up according to the actual installation:

- `BOOST_DIR` - the path to the root of Boost distribution (full source tree is required, not just header files). Version 1.35 or newer is required.
- `TCLINCLUDE_DIR` - the path to the directory where the `Tcl.h` file is located. `/usr/include` and `/usr/local/include` are common for most Unix/Linux installations.
- `TCLLIB_DIR` - the path to the directory where the library file for the Tcl interpreter is located.
- `TCL_LIB` - the name of the Tcl library. Depending on the target operating system, this might be `tcl`, `tcl84`, `tcl8.4` or some variant of this.

Except for `BOOST_DIR`, the default values should work correctly for the typical GNU/Linux installation, so minor modifications will be necessary for other systems only.

To compile Vera++ after setting the above paths and names correctly just execute `make` in the main Vera++ directory (above the `src` directory).
After successful compilation the `vera++` executable will appear in the main Vera++ directory.

Running Vera++

Vera++ needs to know where the rules and transformation scripts are located. The following rules are applied:

- If the `VERA_ROOT` environment variable is defined, it is used as the name of the directory where the `scripts` subdirectory with scripts should be located, otherwise
- If the `HOME` environment variable is defined, then the `~/.vera++` directory is used (and it should contain the `scripts` subdirectory with scritps), otherwise
- The current directory should contain the `scripts` subdirectory.

Vera++ recognizes the following parameters:

- `-` - (a single minus) indicates that the list of source file names will be provided on the stdin.
- `-rule` rulename - instructs the program to execute the given rule; note that the name of the rule should not contain the file extension for the script implementing the rule - this is added automatically, so that for example `-rule my_rule` means that Vera++ will find the `my_rule.tcl` script and run it.
- `-profile` profilename - instructs the program to execute all rules defined in the given profile; the profile name is just a name of the file that will be found under the `profiles` directory, the content of this file is a Tcl script that must set a `rules` variable to be the list of all rules that are part of the profile. An example profile definition that groups three rules (L001, L002 and L003) might look like:

      set rules {
          L001
          L002
          L003
      }

  There is always a `default` profile that lists all existing rules - it is used when no profile is named explicitly.
- `-exclusions` exclusionsfilename - instructs the program to exclude some source files from rule checks, as described in the given file; the content of this file is a Tcl script that must set a `ruleExclusions` array, where keys are rule names and values are lists of files to omit for the given rule. For example:

      set ruleExclusions(L002) {
          some_file.cpp
      }

      set ruleExclusions(T005) {
          some_file.cpp
          some_other_file.cpp
      }

  Note that the given file names are compared for exact match with the source file names that are provided as parameters to Vera++. This means that links in paths are not resolved for comparison purposes.
- `-param` parameterassociation - provides the value of the named parameter to the scripts (see the documentation for each script to see whether it recognizes any parameters); the parameter association has the form `name=value`.
- `-paramfile` filename - instructs the program to read parameter values from the given file; each parameter association should be placed in a separate line of this file.
- `-transform` transformationname - instructs the program to execute a single named transformation; the naming scheme is the same as for the `-rule` option.
- `-showrules` - includes the name of the rule in each report line.
- `-nofail` - instructs the program to always report success exit code, even after encountering runtime errors.
- `-nodup` - instructs the program to omit duplicated messages in the final report (the duplicates can be a result of violating the same rule many times in the same line of source code).
- `-version` - prints the program version information and exits.
- `-help` - prints the list of recognized options and exits.
- All other arguments are treated as source file names if they have appropriate extensions and ignored otherwise.

Examples of executing Vera++ with rules:

To execute all default verification rules against the file `file.cpp`, run:

`$ vera++ file.cpp`

To execute only rule `L001` (this rule ensures that there is no trailing whitespace in each source line) against the same file, run:

`$ vera++ -rule L001 file.cpp`

To execute rule `L004` (this rule checks for too long source lines) with the parameter value providing 78 as the maximum line length, run:

`$ vera++ -rule L004 -param max-line-length=78 file.cpp`

To execute all rules from your favourite profile (assuming that the `my_favourite` profile definition is stored in the `profiles` directory) against all header files in the current filesystem subtree, run:

`$ find . -name '*.h' | xargs vera++ -profile my_favourite`

Note: Vera++ collects the reports generated by each rule and prints them out (on stderr) sorted and after all rules were executed. If there were no problem reports, the output of the program is empty.

Examples of executing Vera++ with transformations:

To execute the `trim_right` source code trasformation (it removes the trailing whitespace that the rule `L001` above complained about) on all `.cpp` files in the current directory run:

`$ vera++ -transform trim_right *.cpp`

As a result, each `.cpp` file will be backed up with the additional extension `.bak` and the files will be trimmed by removing trailing whitespace. The exact behaviour is defined by the script named `trim_right.tcl` in the `scripts/transformations` directory.