Meta-Comments - 2020.2 English

Vivado Design Suite User Guide: Using Tcl Scripting (UG894)

Document ID

UG894

Release Date

2021-03-30

Version

2020.2 English

All the procs inside the Tcl scripts must include some mandatory meta-comments. This applies to user procs (exported out of the namespace) as well as helper procs. The Xilinx Tcl Store linter generates error messages if the meta-comments are missing. The meta-comments for all the exported procs must have complete information. The helper procs however can have empty meta-comments, but the meta-comments must be declared.

The meta-comments provide information to the system such as a short description of what the procs are doing, some category information as well as the list of the command line options supported by the procs. The meta-comments must be included between the proc definition and before the first line of code. All of the meta-comments are mandatory.

The list of mandatory meta-comments is as follows:

Summary: Summary of what the proc is doing. This can be a multi-line summary. The summary is displayed inside the GUI as the proc short description.
Argument Usage: List of command line arguments in the proc. This meta-comment is used to build the Help system. Another section in this document describes the supported format.
Return Value: Use this meta-comment to specify the possible return values for the proc. This meta-comment is used to build the Help system.
Categories: List of categories the app belongs to. Use this meta-comment to specify which categories in the Vivado Help system your app should be listed under. In this meta-comment, "Categories:" should be followed by a comma-separated list. By convention, the first category listed should always be xilinxtclstore followed by the app name.

Below is an example of meta-comments needed for a user proc.

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
 …
}

Note: The detailed meta-comments must be included in the user proc being exported out of the namespace, not the proc my_command1 that was created in the sub-namespace with its helper proc.

Below is an example of meta-comment for a helper proc. All the meta-comments are defined although they are empty:

proc ::tclapp::mycompany::template::my_command1::lshift {inputlist} {
  # Summary :
  # Argument Usage:
  # Return Value:
  # Categories:
  # The code starts below
 …
}

To summarize, the rule is that all Tcl procs inside the scripts must include all the meta-comments. However, on the user procs exported from the namespace need to have detailed information.