Vera++ Community Edition - manual

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++.

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:

• 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.