はじめに
Understand APIとは
Understandの解析情報からさまざまな情報を参照可能なAPIとなります。
最近ではPython APIがよく利用されております。
APIを取り上げた過去の記事は、以下よりご確認いただけます。
Understand APIのご利用に必要なライセンス
Understand APIの実行には、API付きのライセンスが必要になります。
詳しくは貴社ライセンス管理者、またはテクマトリックスの貴社担当営業までお問い合わせください。
関連FAQ
Understand APIに関するFAQは以下をご確認ください。
- Understand APIとは何ですか？
Understand Python APIを利用する場合のPythonのバージョンを教えてください。 - Understand Python APIの利用方法について教えてください。
※本記事ではupythonコマンドを利用する方法で実行しています。 - Understand APIを用いたサンプルはありますか?
- Understand APIに関するマニュアルはありますか？
本記事の実行環境
- Windows 10 64bit
- Visual Studio Code 1.102.0
- Understand 7.0(Build 1220)
実行準備
使用するプラグイン
この記事で使用するVSCodeプラグインは以下の通りです。
あらかじめインストールしてください。
– Python Debugger
https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy
ワークスペースとなるフォルダー
今回は以下のフォルダーで作業します。存在しない場合は空フォルダーを作成します。
C:\work\work_undFunc\work_undapi
VSCodeを起動後、[ファイル]-[フォルダーを開く…]より上記フォルダーを指定します。
サンプルコードの配置
今回はUnderstandのサンプルプロジェクトに対して、Understand APIスクリプトを実行しようと思います。
使用するサンプルプロジェクト（fastgrep）は以下に保存されています。
C:\Users\(ユーザー名)\AppData\Roaming\SciTools\samples
存在しない場合には、Understand起動後に、一度
[ヘルプ]-[サンプルプロジェクト]-[Fastgrep]を押すことでダウンロードしてください。
今回はfastgrepのソースコードとundプロジェクトを以下のように配置しています。
なお、draw.pyはUnderstand APIを実行するために後述で配置するAPIスクリプトです。
C:\
└── work\
└── work_undFunc\
└── work_undapi\
├── .vscode\
│ └── launch.json
└── fastgrep\
├── fastgrep.und
├── draw.py
└── fastgrep\
├── egrep.c
├── regerror.c
├── ...
└── ...サンプルスクリプトの配置
次にAPIのサンプルスクリプトとして、[draw.py]を作成します。
今回作成するdraw.pyは指定ファイル内の関数のグラフィカルビューを画像ファイルとして出力するスクリプトとなります。
空ファイルが作成されます。
draw.pyに以下のコードを貼り付けて、[Ctrl] + [S] で保存します。
※base_pathとdb_nameはご自身の環境に合わせて変更してください。
※Pythonではインデントの数がブロックを表しているため、コピーする際はインデントが崩れないようご注意ください。
from datetime import datetime
import os
import subprocess
import understand as und
# Understandプロジェクトを開く
base_path = "C:/work/work_undFunc/work_undapi/fastgrep"
db_name = "fastgrep.und" # 解析対象のプロジェクトファイル名
db_path = os.path.join(base_path, db_name)
db = und.open(db_path)
# プロジェクト全体の要約情報を取得
print(f"Number of Files: {len(db.ents('File'))}")
print(f"Number of Functions: {len(db.ents('Function'))}")
print(f"Number of Classes: {len(db.ents('Class'))}")
# 現在の日時を取得し、フォーマット
current_time = datetime.now().strftime('%Y%m%d%H%M%S')
print(current_time)
# 特定のファイルを取得
# graph_type = "Control Flow"
# graph_type = "Calls"
graph_type = "Called By"
OPTIONS = "name=shortname"
VARIANT = "Simplified"
output_dir = os.path.join(base_path, "graph", current_time, graph_type)
os.makedirs(output_dir, exist_ok=True)
# 特定のファイルに定義された関数エンティティを取得
file = db.lookup_uniquename("@l./fastgrep/egrep.c")
functions = file.ents("Define", "Function")
for func in functions:
print(f" {func.longname()}")
callbys = func.refs("callby ~inactive, use ptr ~inactive")
if len(callbys) > 0:
print(f" Call By: {len(callbys)} references")
else:
print(" No Call By references found.")
continue
picture_name = func.name()+".png"
picture_path = os.path.join(output_dir, picture_name)
func.draw(graph_type, picture_path, OPTIONS, VARIANT)
db.close()
launch.jsonの準備
[実行とデバッグ]ボタンのすぐ下にある”launch.jsonファイルを作成します”のリンクを押します。
[Python Debugger]を選びます。
[引き数を含むPythonファイル]を選びます。
上記手順によりlaunch.jsonファイルが表示がされます。
以下の内容をlaunch.jsonに上書きし、[Ctrl]+[S]で保存します。
※nameパラメーターの値は任意の名称を指定ください。
※pythonパラメーターにて指定するupython.exeはお客様の環境に合わせて変更してください。
※programパラメーターにて指定するpyファイルのパスは、ご利用の環境に合わせて変更してください。
{
"version": "0.2.0",
"configurations": [
{
"name": "understand7.0(1220)api",
"type": "debugpy",
"request": "launch",
"program": "C:/work/work_undFunc/work_undapi/draw.py",
"console": "integratedTerminal",
"args": "",
"python": "C://Program Files//SciTools//bin//pc-win64//upython.exe",
}
]
}なお、launch.jsonは以下に作成されています。
C:\work\work_undFunc\work_undapi\.vscode\launch.json
※上記launch.jsonでは起動consoleはintegratedTerminalと指定されています。これはPython DebuggerがVScodeのデフォルトターミナルを利用する設定であり、この設定によりPowershellが利用される場合があります。Python DebuggerをVScode上のCommand Promptから起動したい場合には、VScodeのコマンドパレット(Ctrl+Shift+P)から”Preferences: Open User Settings(JSON)”と入力し、以下を追記して保存することで、Command Promptを利用可能です。
"terminal.integrated.defaultProfile.windows": "Command Prompt", "terminal.integrated.profiles.windows": {
"Command Prompt": {
"path": "C:\\Windows\\System32\\cmd.exe"
}
}
VSCodeのプラグイン”Python Debugger”を使用したUnderstand APIの実行
実行
再生マークのタブを選び、[understand7.0(1220)api]を押すと実行されます。
スクリプトを実行するとbase_pathで指定したフォルダーにgraphフォルダーが作成され、
この配下にいくつかの関数に対するCalled Byグラフの画像がpngファイルとして出力されます。
※依存元がある関数のみ出力されます。
ブレークポイントを貼って、一時停止させたり、ウォッチ式で変数の値を確認したり、
以下のようにステップ実行することも可能です。
F5：実行
F10：ステップオーバー実行
F11：ステップイン実行
終わりに
今回はUnderstand Python APIを使ったスクリプトをVSCodeで実行する場合の手順をご紹介いたしました。
Python APIを利用することで、Understandプロジェクトからさまざまな情報を抽出することが可能です。
なお、Understand APIライセンスのご試用をご希望の場合には、
テクマトリックスの貴社担当営業、またはSciToolsテクニカルサポートセンターまでお問い合わせください。
それでは、Understand APIをぜひお試しください。
