Plugins

PERL API

Overview

Understand includes a PERL API which allows you to directly query the Understand database. If you want to create your own report, or gather information in a manner that we didn't foresee in Understand, you can access the information yourself via the API. The API can be accessed in several different ways: most of the scripts are designed to be run from Understand's GUI on the currently opened database. They can also be run from the command line, and some plugins are designed to interact directly with Understand.


Run Scripts in Understand

To run a script from inside of Understand, use Tools->Run a Command, configure any necessary parameters, and hit run. The resulting output can then be double-clicked to visit the referenced source.

perl commands in Understand 


Run Scripts from the Command Line

Scripts can be run from the command line using uperl, a special PERL executable included in Understand's bin directory. To run a script from the command line, specify the script, the database and any options:

uperl scriptName.pl -db myproject.udb [Options]

So to run this same script from the command line, you could use the following command:

uperl command line

If you would rather access the Understand API from your own customized Perl installation, just add <SciTools>/bin/pc-win32/Perl/STI/Maintain to your Perl include path. On non-Windows systems, you will also need to create an STIHOME environment variable that points to the <SciTools> directory.


Use Understand Plugins

Plugins are special Perl scripts written specifically to interact with the Understand GUI. You can quickly tell them apart by the file extension: regular scripts use .pl while plugin scripts use .upl. Plugins give you the power to interact with specific entities inside of Understand, for example you can right click on an entity and run a custom (interactive) report on it, or generate your own graph.

Plugins are installed by placing them in the appropriate folder. Once installed they will show up in the context menu or in the main menu depending on the type of plugin.

interactive report

Several of the graphs included in Understand are actually plugin scripts as well, including the control flow graph and the butterfly graph. They can be customized, or used as a starting point for creating your own graphs.

butterfly graph


Write Your Own Scripts

Here is a collection of tutorials on getting started with the API. For more details, refer to the Perl API documentation under the Help menu in Understand, or here.

Sample Scripts

The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/perl folder.