Install and Uninstall Hook 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

Each app can have an install and uninstall proc. After they are defined, the procs are recognized by the Tcl Store and automatically called in specific situations:

  • The install proc is automatically called when the app is installed. This is the first proc called by the Tcl Store during the install process. After the app has been installed, the install proc is no longer called. During the subsequent start of Vivado tools, the install proc is not called because the app is only loaded.
  • The uninstall proc is automatically called when the app is uninstalled. This is the last proc called by the Tcl Store during the uninstall process.

The name of the install proc is ::tclapp::<company>::<app>::install and the name of the uninstall proc is ::tclapp::<company>::<app>::uninstall.

For example:

::tclapp::mycompany::template::install
::tclapp::mycompany::template::uninstall

The install and uninstall procs can be used to handle, for example, a custom GUI button. The button can be installed by the install proc and removed by the uninstall proc. Multiple custom GUI buttons can be associated with an app. After a button is installed, it is available through all subsequent calls of the same Vivado tools version, until the app is uninstalled. The install and uninstall procs are optional. If the app does not use the install and uninstall procs, these procs can either be left undefined or defined with an empty body.

Below is an example of empty procs:

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
}

The example procs below reference a custom GUI button:

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
}