Using Understand from the Command Line with Und

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.screenshot.14


Interactive Mode

Interactive mode is not want 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.

Command What it does
und Opens und in interactive mode
create –languages C++ c:\project.udb Create and open a new C++ project
add c:\pathtosrc Add the specified directory of source to the project
settings -c++MacrosAdd WIN32 PI=3.14 Define new C++ Macros
settings -c++IncludesAdd c:\dir1 c:\dir2 Add new C++ Include directories
settings –reportOutputDirectory c:\htmlDir Set the path for the HTML reports
settings –metrics all Specify to generate all metrics
settings –metricsOutputFile c:\metrics.csv Set the path for the metrics csv file
analyze Analyze the project
report Generate the HTML reports
metrics generate the metrics csv file
quit exit interactive mode

If you need to customize these commands more, und help and und help <command> 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

screenshot.17 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

screenshot.11 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.udb
>und add c:\pathtosrc c:\project.udb
>und settings -c++MacrosAdd WIN32 PI=3.14 c:\project.udb
>und settings -c++IncludesAdd c:\dir1 c:\dir2 c:\project.udb
>und settings -reportOutputDirectory c:\htmlDir c:\project.udb
>und settings -metrics all c\:project.udb
>und settings -metricsOutputFile c:metrics.csv c:\project.udb
>und analyze c:\project.udb
>und report c:\project.udb
>und metrics c:\project.udb

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