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:

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:

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:

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:

Vera++ recognizes the following parameters:

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.