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 Understand.app/Contents/MacOS/und
Command What it does
Interactive Mode
Command What it does
| Command | What it does |
|---|---|
| und | Opens und in interactive mode |
| create -languages C++ c:\project.und | 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 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 [email protected] 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