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.
Check out our public plugins git repository here.
If we don't already have what you need and you don't have the manpower or the time to get it done right now, then reach out to us at [email protected] and we will work with you to determine exactly what you need, get you a quote, and get the job done for you as quickly as possible.
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.
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:
Using your own Perl Installation
If you would rather access the Understand API from your own customized Perl 5.34.0 installation, just add /bin/pc-win32/Perl/STI to your Perl include path, on OSX the default path to uperl is /Applications/Understand.app/Contents/MacOS/uperl. On non-Windows systems, you will also need to create an STIHOME environment variable that points to the directory. It may also be necessary to set the LD_LIBRARY_PATH environment variable to /bin/linux64,. Keep in mind if using your own installation, that it will need to have thread support since our Understand Perl module is built with thread support. For example, when using Perlbrew, install it with this command: perlbrew install perl-5.34.0 -Duseithreads to build it with thread support, making it compatible with our perl module.
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 dragging and dropping them into the Understand GUI or placing them in the Scitools/conf/plugins folder. Once installed they will show up in the context menu or in the main menu depending on the type of plugin.
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.
Write Your Own Scripts
We have many tutorials for helping get started with the API:
Part 1: Writing Your First Script
Part 2: Entities and References
Part 3: Lexers and Lexemes
Part 4: Custom Graphs
Part 5: Interactive Reports
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.