Copyright 2006-2007 Maciej Sobczak
Introduction
Compiling
Running
Index of available rules
Index of available transformations
Script API
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++.
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.
Vera++ needs to know where the rules and transformation scripts are located. The following rules are applied:
VERA_ROOT
environment variable is defined, it is used as the name of the directory where the scripts
subdirectory with scripts should be located, otherwiseHOME
environment variable is defined, then the ~/.vera++
directory is used (and it should contain the scripts
subdirectory with scritps), otherwisescripts
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.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.