このセクションのコード例では、アプリ名が template、アプリを提供および管理する企業の名前が mycompany で あるとします。
用語
• ユーザー プロシージャ: ユーザーが実行するプロシージャ。
• ヘルパー プロシージャ: ユーザー プロシージャでタスクを実行するためにバックグラウンドで使用されるプロシ ージャ。ヘルパー プロシージャは、ユーザーによって直接実行されることはなく、ヘルプ システムには含まれま せん。
ユーザー プロシージャとヘルパー プロシージャ
Tcl スクリプトでは、複数のユーザー スクリプトを定義できます。ユーザー プロシージャは、ユーザーにより実行さ れる Tcl プロシージャ (コマンド) です。前述のように、すべてのユーザー プロシージャはアプリの名前空間からエク スポートする必要があります。
ユーザー プロシージャに加え、Tcl スクリプトではヘルパー プロシージャも定義できます。ヘルパー プロシージャは ユーザー プロシージャでのみ使用され、ユーザーには使用できないようにする必要があるので、名前空間からエクス ポートしません。どのプロシージャをユーザーがコマンド ライン インターフェイス (スクリプトまたは Tcl コンソー ル) から実行できるようにするかをシステムで指定するには、プロシージャを名前空間からエクスポートするのが唯 一の方法です。
ユーザープロシージャがヘルパープロシージャを使用する場合、アプリの下にサブ名前空間を作成し、ユーザープ ロシージャとヘルパー プロシージャをその下に移動することをお勧めします。これにより、アプリ内のヘルパー プ ロシージャ間で名前の競合が発生するのを防ぐことができます。これは、さらにスクリプトを独自のヘルパープロシ ージャと共に追加する場合に特に重要です。
次のコードは、Tcl コードに推奨される構造を示します。ユーザー プロシージャはアプリの名前空間のすぐ下にあり ますが、これはサブ名前空間 ::tclapp::mycompany::template::my_command1 の下に移動された元のプロシ ージャを呼び出すために使用されるラッパーです。
namespace eval ::tclapp::mycompany::template { namespace export my_command1
}proc ::tclapp::mycompany::template::my_command1 { args } { # Calling the original code moved under the sub-namespace
uplevel [concat ::tclapp::mycompany::template::my_command1::my_command1
$args]
}eval [list namespace eval ::tclapp::mycompany::template::my_command1 { } ]proc ::tclapp::mycompany::template::::my_command1::my_command1 { args } { # Here is the code of the original proc
}proc ::tclapp::mycompany::template::my_command1::helper1 { args } { # Here is the code of the helper proc
}
注記: サブ名前空間 ::tclapp::mycompany::template::my_command1 は、その中にプロシージャを定義する前 に作成する必要があります。サブ名前空間を作成する構文は、リンターからのエラー メッセージを回避するため、
「eval [list namespace eval ::tclapp::mycompany::template::my_command1 {}]」とする必要があ ります。
注記: コードを解読しやすくするため、上記のコードにはこのセクションの後の方で説明する必須のメタコメントは 含まれていません。
フック プロシージャのインストールおよびアンインストール
各アプリケーションには、installinstall および uninstalluninstall プロシージャがあります。これらのプロシー ジャを定義すると、Tcl Store で認識され、特定の状況で自動的に呼び出されるようになります。
• installinstall プロシージャは、アプリケーションをインストールするときに自動的に呼び出されます。インス トールプロセス中に Tcl Store で最初に呼び出されるプロシージャです。アプリをインストールした後は、
installinstall プロシージャは呼び出されません。その後 Vivado ツールを起動したときには、アプリは既に読み 込まれているので、install プロシージャは呼び出されません。
• uninstallプロシージャは、アプリケーションをアンインストールするときに自動的に呼び出されます。アンイ ンストール プロセス中に Tcl Store で最後に呼び出されるプロシージャです。
installinstallプロシージャの名前は::tclapp::<company>::<app>::installで、uninstalluninstallプロ シージャの名前は ::tclapp::<company>::<app>::uninstall です。
次に例を示します。
::tclapp::mycompany::template::install ::tclapp::mycompany::template::uninstall
installinstall および uninstalluninstall プロシージャは、カスタム GUI ボタンなどの処理に使用できます。ボタ ンを installinstall プロシージャを使用してインストール、uninstalluninstall プロシージャを使用して削除でき ます。1 つのアプリに複数のカスタム GUI ボタンを関連付けることができます。ボタンをインストールすると、アプ リをアンインストールするまで、同じ Vivado ツール バージョンを起動したときにそのボタンを使用できます。
installinstall および uninstalluninstall プロシージャはオプションです。アプリケーションが install および uninstall プロシージャを使用しない場合、これらのプロシージャは未定義のままにするか、ボディ部分は空で定 義できます。
次に、空のプロシージャの例を示します。
proc ::tclapp::mycompany::template::install { args } { # Summary :
# Argument Usage:
# Return Value:
# Here is the code of the install proc
# For example, a GUI custom button could be added }proc ::tclapp::mycompany::template::uninstall { args } { # Summary :
# Argument Usage:
# Return Value:
# Here is the code of the uninstall proc
# For example, the GUI custom button added by the install proc should be removed
}
次のプロシージャ例では、カスタム GUI コマンドを作成しています。
proc ::tclapp::mycompany::template::install { args } { # Summary :
# Argument Usage:
# Return Value:
## Add Vivado GUI button for the app
if { [lsearch [get_gui_custom_commands] myButton] >= 0 } {
puts "INFO: Vivado GUI button for the app is already installed.
Exiting ..."
return -code ok
} puts "INFO: Adding Vivado GUI button for the app"
create_gui_custom_command -name "myButton" \ -menu_name "Do something" \
-command "::tclapp::mycompany::template::my_command1" \ -show_on_toolbar \
-run_proc true
create_gui_custom_command_arg -command_name "myButton" -arg_name
"Top_Module"
-default "\[lindex \[find_top\] 0\]"
create_gui_custom_command_arg -command_name "myButton" -arg_name
"Output_Directory" -default "-output_dir report" -optional
create_gui_custom_command_arg command_name "myButton" arg_name "Force" -default
"-force" -optional return -code ok
}proc ::tclapp::mycompany::template::uninstall { args } { # Summary :
# Argument Usage:
# Return Value:
if { [lsearch [get_gui_custom_commands] myButton] >= 0 } { puts "INFO: Vivado GUI button for this app is removed."
remove_gui_custom_commands "myButton"
} else {
puts "INFO: Vivado GUI button for this app is not installed."
} return -code ok }
変数の共有
変数に関する重要な規則は、グローバル変数は禁止されているということです。ザイリンクス Tcl Store リンターは、
スクリプト内のグローバル変数をチェックし、グローバル変数が定義されているとエラー メッセージを表示します。
アプリに含まれる複数のプロシージャで変数を共有する必要がある場合は、その名前空間内で宣言します。これには、
キーワード variable を使用して名前空間内で変数を作成します。このように作成した変数は、グローバル変数のよ うに使用できますが、その名前空間内のみで使用可能です。
次のコードでは、同じ名前空間に含まれるすべてのプロシージャで 共有可能な変数 verbose を作成しています。こ の変数は 0 に初期化されます。
namespace eval ::tclapp::mycompany::template { variable verbose 0
}
プロシージャ内でこの変数にアクセスするには、プロシージャ内で変数をキーワード variable を使用して宣言しま す。
次に例を示します。
proc ::tclapp::mycompany::template::::my_command1::my_command1 { args } { variable verbose
# The variable verbose can be accessed here set verbose 1
}proc ::tclapp::mycompany::template::my_command1::helper1 { args } { variable verbose
# The variable verbose can be accessed here if {$verbose} {
..
}}
注記: 変数 verbose には、完全な名前空間修飾子を使用すれば、グローバル名前空間を含むどの名前空間からでもア クセスできます。次に例を示します。
set ::tclapp::mycompany::template::verbose 1
メタコメント
Tcl スクリプト内のすべてのプロシージャには 、必須のメタコメントを含める必要があります。この規則は、名前空間 からエクスポートされているユーザー プロシージャとヘルパー プロシージャの両方に適用されます。メタコメント が含まれていない場合、ザイリンクス Tcl Store リンターによりエラー メッセージが生成されます。エクスポートさ れたすべてのプロシージャのメタコメントには 、完全な情報が含まれていることが必要です。ヘルパー プロシージャ のメタコメントは空にすることが可能ですが、メタコメントは宣言する必要があります。
メタコメントは、プロシージャの機能の簡単な説明、カテゴリ情報、プロシージャでサポートされるコマンド ライン オプションのリストなどの情報をシステムに提供します。メタコメントは、プロシージャ定義とコードの最初の行の 間に挿入する必要があります。すべてのメタコメントが必須です。
必須のメタコメントは、次のとおりです。
• Summary: プロシージャの機能のサマリ。複数行にできます。このサマリは、[Xilinx Tcl Store] ダイアログ ボック スにプロシージャの説明として表示されます。
• Argument Usage: プロシージャのコマンド ライン引数のリスト。ヘルプ システムを構築するのに使用されます。
このガイドの別のセクションで、サポートされるフォーマットを示します。
• Return Value: プロシージャの戻り値。ヘルプ システムを構築するのに使用されます。
• Categories: アプリのカテゴリのリスト。アプリをリストする Vivado ヘルプ システムのカテゴリを指定します。
「Categories:」の後にカテゴリをカンマで区切ってリストします。慣習として、最初にxilinxtclstoreを 指定し、その後にアプリ名を指定します。
次に、ユーザー プロシージャに必要なメタコメントの例を示します。
proc ::tclapp::mycompany::template::my_command1 { args } { # Summary: Multi-lines summary of
# what the proc is doing # Argument Usage:
# [-verbose]: Verbose mode
# [-file <arg>]: Report file name # [-append]: Append to file
# [-return_string]: Return report as string # [-usage]: Usage information
# Return Value:
# return report if -return_string is used, otherwise 0. If any error occur TCL_ERROR
is returned
# Categories: xilinxtclstore, template # The code for the proc starts below }
注記: サブ名前空間にヘルパープロシージャと共に作成されたプロシージャmy_command1ではなく、名前空間から エクスポートされるユーザー プロシージャに詳細なメタコメントを含める必要があります。
次に、ヘルパー プロシージャのメタコメントの例を示します。すべてのメタコメントが定義されていますが、空で す。
proc ::tclapp::mycompany::template::my_command1::lshift {inputlist} { # Summary :
# Argument Usage:
# Return Value:
# Categories:
# The code starts below }
スクリプトに含まれるすべての Tcl スクリプトにすべてのメタコメントを含める必要がありますが、詳細情報を含め る必要があるのは、名前空間からエクスポートされるユーザー プロシージャです。
コマンド ライン引数のメタコメント
ユーザー プロシージャのコマンド ライン引数は、ユーザー プロシージャ内でメタコメント Argument Usage を使 用して説明する必要があります。このメタコメントは、<command> -help が実行されたとき、または [Xilinx Tcl Store] ダイアログ ボックスでプロシージャのヘルプが表示されたときに、ヘルプ システムでメッセージを生成するの に使用されます。次に例を示します。
# Argument Usage:
# [-verbose]: Verbose mode
# [-file <arg>]: Report file name # [-append]: Append to file
# [-return_string]: Return report as string # [-usage]: Usage information
ヘルプ システムでこのメタコメント Argument Usage が使用され、次のメッセージが表示されます。
Syntax:
xilinx::designutils::write_template [-verbose] [-file <arg>] [-append]
[-return_string] [-usage] [-quiet]
Usage:
Name Description
[-verbose] Verbose mode Default: 0 [-file] Report file name Default: None [-append] Append to file Default: 0
[-return_string] Return report as string Default: 0
[-usage] Usage information Default: 0
[-quiet] Ignore command errors
メタコメントArgument Usageは、Tcl プロシージャを呼び出す前の Vivado によるコマンドライン引数の前処理で はないということに注意してください。ヘルプ システムで使用されるだけです。プロシージャの Tcl コードでコマン ド ライン引数を処理する必要があります。