Install & run plugins (Plugin Manager)¶
Understand metrics, graphs, architectures, and reports are all extendable with scripts, and so are CodeCheck checks. Understand ships a large library of scripts and lets you add your own. Manage them all (built-in and scripted) from the Plugin Manager.
CodeCheck checks
CodeCheck checks are also extendable with scripts, but are managed as part of building a CodeCheck configuration, not through the Plugin Manager. CodeCheck configurations are listed in the Plugin Manager for convenience. For example, it allows the Hersteller Initiative Software NOMV metric to link to the configuration that must run in the background for it to function correctly.
Open the Plugin Manager¶
Open the plugin manager with Tools → Plugin Manager (a project must be open). It lists every plugin Understand has found — built-in, shipped, and user-installed. You'll also find shortcuts to the plugin manager scoped to particular plugin kinds, like Metrics → Configure Metrics to open the plugin manager scoped to metrics.
Enabling plugins¶
Enabled plugins appear in relevant GUI views. For example: enable the Strict Cyclomatic Complexity metric to make it visible in the Metrics Browser for applicable entities, or enable the Shared Tasks - By Function graph to make it visible in an Architecture's "Graphical Views" menu.
Most built-in plugins are always enabled
Only built-in metrics can be enabled/disabled through the Plugin Manager. Other built-in plugins are always on.
Filtering plugins¶
Individually enabling many plugins can be tedious, so the Plugin Manager provides powerful filtering that can be used in combination with enable all (the checkbox in the top right of the table header) for bulk enabling. The right hand panel initially shows available filters and updates them as you apply them.
Clicking on a filter applies it, and applied filters are visible to the right of the search bar. Clicking on an applied filter toggles it off again. You can also use the search bar to filter the table of plugins.
Plugin families
Plugins, especially metrics, often come in groups that you want to enable together. For example, to see Strict Cyclomatic Complexity, you'll want to turn on not only that metric, but also its aggregated versions (sum, average, and max) and comparison versions. Grab them all by scrolling to the "Cyclomatic" filter heading and selecting "Strict". Similar filters exist for other common groups.
Once you click on a plugin, the right hand panel will update to show the details of that plugin. You can return to the filters view by clicking Back or by clicking in whitespace in the table to clear the selection. You can also use the Home button to return to the initial view, but that will clear all filters.
Plugin details¶
Select a plugin to view its details. Additional buttons will appear above the right hand panel, and the right hand panel will update with plugin details. The first part of the plugin details view shows all the filters for the plugin. Those filters are clickable, just like the filters page. The remaining content is the plugin's description which can include links to other plugins and external pages. By convention, the description strings shipped with Understand's own plugins end external links with ↗.
The additional buttons are:
| Action | Button | Effect |
|---|---|---|
| Enable / Disable | Turn a plugin on or off, same as checking it in the list | |
| Run | Run the selected plugin now. Codecheck configurations will have a drop-down option to run in background. | |
| Customize | Make an editable copy of a shipped script in your per-user plugin folder so you can modify it. | |
| Configure | For metrics with options only, configure the options for the current project |
Install a plugin¶
Add your own plugins by installing them. There are several ways:
Drag a .upy file onto the Understand main window. Understand recognizes it as a plugin and
offers Install (or Edit); Install copies it into the correct per-user plugin subfolder and
enables it.
In the Plugin Manager, click Add Plugin and pick the .upy from disk.
Drop the file into your per-user plugin directory (see the table below), then Rescan Plugins.
Where plugins live¶
The Plugin Manager reads two places: the plugins shipped with Understand, and your per-user
plugin directory, organized into a subfolder per type (Graph, Metric, Codecheck, IReport,
Arch):
| OS | Per-user plugin base |
|---|---|
| Windows | %APPDATA%\SciTools\plugin\<Type> (i.e. …\AppData\Roaming\SciTools\plugin\<Type>) |
| macOS | ~/Library/Application Support/SciTools/plugin/<Type> |
| Linux | ~/.config/SciTools/plugin/<Type> |
After editing a plugin's source
In the Plugin Manager (Tools → Plugin Manager) click Rescan Plugins to discard cached plugin information and reload from disk — your changes then take effect without restarting Understand.
If an installed plugin doesn't show up at all, it usually has a syntax or import error — see the plugin gotchas.
Next steps¶
To write your own, see Write a plugin, or build one with AI if you'd rather describe what you want than write it by hand. For the Python API itself, start with Python API: getting started, then browse the sample & solution scripts (cookbook) for working examples to adapt.