User Procs and Helper Procs - 2024.1 English

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

Document ID
UG894
Release Date
2024-05-30
Version
2024.1 English

A Tcl script can define multiple user procs. A user proc is a Tcl proc (that is, a command) expected to be executed by the user. As stated previously, all the user procs need to be exported from the namespace of the app.

In addition to user procs, a Tcl script can define some helper procs. Helper procs are only used by the user procs and should not be exposed to the user. As a result, helper procs should not be exported from the namespace. Exporting a proc from the namespace is the only way to specify to the system which of the procs should be exposed to the user through the command line interface (scripting and/or Tcl Console).

When a user proc uses helper procs, it is recommended to create a sub-namespace under the app and move the user proc and helper procs below it. Doing this ensures that there is no name collision between all the helper procs within the app. It is especially important as the app grows in size and more scripts are added along with their own helper procs.

The code below illustrates the recommended structure for the Tcl code. The user proc still exists directly under the app's namespace, but it is just a wrapper used to call the original proc that has been moved under the sub-namespace, ::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
}
Note: The sub-namespace ::tclapp::mycompany::template::my_command1 needs to be created prior to defining the procs inside. The syntax to create the sub-namespace must be eval [list namespace eval ::tclapp::mycompany::template::my_command1 {}] to prevent an error message from the linter.
Note: To make the code easier to read, the above code does not include the mandatory meta-comments that are discussed later in this section.