Many teams want to quickly generate Understand’s HTML reports and metrics as part of their regular build process or automate project creation in some other way. The command line tool ‘und’ provides a lot of options for doing exactly this. In this walk through I am going to create an Understand project from the latest version of my source code and generate the html reports and metrics for that version of the code. Since und has several different modes, I will show how this would be done in each mode.

Interactive Mode

Interactive mode is not what you want to use for automating a process, but is useful for testing commands and quick tasks. Running through these commands in interactive mode is a good test to make sure everything is configured the way you want. The path to und is SciTools/bin/<PLATFORM>/und or on Mac

Command What it does

Interactive Mode

Command What it does

CommandWhat it does
undOpens und in interactive mode
create -languages C++ c:\project.undCreate and open a new C++ project
add c:\pathtosrcAdd the specified directory of source to the project
settings -c++MacrosAdd WIN32 PI=3.14Define new C++ Macros
settings -c++IncludesAdd c:\dir1 c:\dir2Add new C++ Include directories
settings -reportOutputDirectory c:\htmlDirSet the path for the HTML reports
settings -metrics allSpecify to generate all metrics
settings -metricsOutputFile c:\metrics.csvSet the path for the metrics csv file
analyzeAnalyze the project
reportGenerate the HTML reports
metricsgenerate the metrics csv file
quitexit interactive mode

If you need to customize these commands more, und help and und help provide thorough documentation. To see all of the options available for a project run und list -all settings myproject.udb the follow the directions at the beginning of und help settings to turn each option into a command line switch. Feel free to contact us at if you have questions or run into roadblocks.

Batch Mode

Once you have identified the commands you want to run using interactive mode, place those exact commands in a text file. No need to include the first und command or the quit command, those are handled automatically.

Then all you have to do is run:

und myCommands.txt

and all the commands in the file will be processed in order. In previous versions of und the project database was opened and closed between each command, when many commands were run on large projects, this could cause significant slowdown. In the new version of und the database stays opened in Interactive and Batch Mode leading to much quicker results.

Line Mode

Single line mode lets you run each command directly in the shell. The Understand database is opened and closed for each command and needs to be specified on each line. It can be specified with the –db parameter, or included as the last parameter.

So doing the same thing in Line Mode would look like:

und create -languages C++ c:\project.und
und add c:\pathtosrc c:\project.und
und settings -c++MacrosAdd WIN32 PI=3.14 c:\project.und
und settings -c++IncludesAdd c:\dir1 c:\dir2 c:\project.und
und settings -reportOutputDirectory c:\htmlDir c:\project.und
und settings -metrics all c:project.und
und settings -metricsOutputFile c:metrics.csv c:\project.und
und analyze c:\project.und
und report c:\project.und
und metrics c:\project.und

Again, this method is a little slower since it opens the database each command, but depending on your build process, it may be easier to implement.

Single Line Mode

The same commands can all be run on the same line if desired, which will only open the database once and will be faster, although harder to read. The commands will run in the order entered and the settings commands can all be grouped together.

und -db c:\project.und create -languages C++ add c:\pathtosrc settings -c++MacrosAdd WIN32 PI=3.14 -c++IncludesAdd c:\dir1 c:\dir2 -reportOutputDirectory c:\htmlDir -metrics all -metricsOutputFile c:\metrics.csv analyze report metrics