| Store | Cart

ActiveState Docs

TDK 5.3 Documentation

Loading...

Cross Reference Tool

The Tcl Dev Kit Cross Reference Tool (XRef) is a graphical browser that maps out the structure of a Tcl program and helps make complex code more understandable. The XRef tool scans Tcl source code, and then builds a cross-referenced database showing you the relationships among Tcl code components. These components include packages, files, namespaces, commands, and variables. Each Tcl component is presented in a tree hierarchy that can be expanded to display where the code is defined, declared, used, and located.

The XRef tool is useful for building, debugging, and maintaining Tcl code. For example, when changing a variable definition, use the XRef tool to identify the files and commands where the variable is declared, and then update them to the new variable definition.

The Tcl Dev Kit Cross Reference Tool can be used to extract Tcl component information from programs and packages contained in TclApp (or Prowrap) projects, Tcl Dev Kit Package definitions (".tap" files), and from Komodo project files.

Cross Reference Tool features include:

  • Switching between hierarchical views to gain a higher-level or lower-level understanding of any Tcl source component.
  • Drilling down into specific areas of code.
  • Finding dependencies between commands, variables etc.
  • Browsing from a listed namespace, command, or variable definition and jumping to the actual source code where it is declared. Note: XRef will launch Tcl source code in the Komodo editor if it is installed.
  • Filtering components based-on packages, files, namespaces, commands and variables.
  • At-a-glance overview of code areas that could be affected by changing a command or variable definition.

The XRef BWidgets demo uses the Cross Reference Tool to extract component information from the BWidgets package. See the XRef BWidgets Demo for more information.

Top

Overview

This section lists the platforms and Tcl versions that the Tcl Dev Kit Cross Reference Tool supports. It then describes how to start the tool and provides a tour of the main window.

Supported Tcl Versions

The Tcl Dev Kit Cross Reference Tool works with Tcl version 8.4 or greater.

Starting the Tcl Dev Kit Cross Reference Tool

The Cross Reference tool is an application that builds a database of program components, including packages, files, namespaces, commands and variables.

Windows

  • Start Menu: Start | Programs | ActiveState Tcl Dev Kit | Tcl Dev Kit Cross Reference Tool
  • Command Line: tclxref.exe

Unix

  • Shell Prompt: tclxref

Note: When using the command line to start the XRef tool, you can specify the filename of a database to load. See Opening a Database for more information.

Cross Reference Tool Explorer

The Cross Reference Tool explorer window consists of the following components:

main explorer

Note: To change the font size displayed in the Cross Reference Tool Explorer, press Ctrl-plus to increase the font size or Ctrl-minus to decrease the displayed font size. If using Windows with a mouse wheel, you can alternatively press the Ctrl key and then rotate the mouse wheel to increase or decrease the font size displayed in the Cross Reference Tool Explorer.

Menu

menu buttons

The menu contains File and Help content.

  • File: Use the File menu to open, close, and save cross-referenced databases. See Opening a Database for more information.
  • Help: Use the Help menu to access online help. Select Help | Help topics.

Component Display

The component display lists the scanned component data. Where applicable, component data is displayed in expandable hierarchical lists. Each list can be drilled down, using expanding and collapsing tree nodes, to display the commands and variables associated with a particular component.

Component Tabs

The Cross Reference Tool displays Tcl program component types on individual tabs. Each tab presents the same scanned database content in a different view, depending on the component tab selected. For example, the Files tab shows the components used and defined within a particular file. These file components could include: namespaces, commands, variables, and packages. The Commands tab, however, provides a narrower view of the scanned database as only the lower-level variables associated with a particular command are displayed. By switching between these two component tab views, you gain a higher or lower-level understanding of any Tcl source component. The component tabs include:

Component Filters

Each component tab has a unique filter that limits the number of components listed in the display window. Component Filters are opened from any component tab using the Filter button. Each filter can be configured to find exact matches, and to perform glob-style matching (using the asterisk (*) to match any sequence of characters and a question mark (?) to match any single character). When configured, only elements matching that pattern are displayed.

Note: Only top-level nodes of a hierarchical list are filtered. Node children are not filtered.

XRef Component Explorers

XRef Component Explorers focus on the low-level details of a single component. An XRef Component Explorer is invoked from any component tab using the Open button. Each component tab launches a unique component explorer interface to view the specifics of the selected component.

Component Source Code Viewer

The Component Source Code Viewer is only applicable to those without an ActiveState Komodo installation. The XRef Component Source Code Viewer displays scanned source code on systems without a Komodo installation. If Komodo is installed, all component source code is loaded in Komodo and the Component Source Code Viewer is never invoked.

Top

Packages Tab

The Packages tab displays the Tcl packages that are used and defined within the scanned Tcl source code. The #Provides and #Requires columns display the number of times each package is used within the database. The #Provides column indicates the total number of times the scanned source files contain a require statement for a selected package. The #Requires column lists the number of packages that a selected package uses. Click a column title to sort package content in ascending or descending order. The current sort column selected is shaded pink.

  • The icon denotes a package component.

Filtering Packages

To filter packages:

  1. Click the Filter button. The Filter Packages screen appears.
  2. Enter the filter conditions, based-on any combination of the following:
    • Name: Package name.
    • #Provides: Number of times the package has been required.
    • #Requires: Number of packages this package requires.
  3. Select a filter action:
    • Click Ok to enable and close the filter.
    • Click Apply to enable the filter. The filter screen stays open.
    • Click Cancel to abort and close the filter.

Opening Package Details

Use the Open button to view details on a particular package, such as the name of the file where a required statement calls the package. Opening a package's details invokes an XRef Package Explorer window, which displays lower-level code details specific to the package selected. To open a package's details in an XRef Package Explorer window:

  1. Select the desired package name.
  2. Click the Open button. An XRef Package Explorer window appears. This explorer is titled 'XRef Package: [package_name]'. Note: Alternatively, double-click the package name to invoke an XRef Package Explorer.

The XRef Package Explorer displays the files that are used and defined within the selected package component. Toggle between the Uses and Definition tabs to view what files are used and where those files are defined. The File column lists all files the package uses or defines. The Line column provides the source-code line number. This combination of XRef Package Explorer tabs and columns are useful for obtaining very low-level details on the file where the package is required.

It is possible to invoke numerous XRef Package Explorers while inspecting the scanned database. To continue exploring package file details, click the Open button once again. The total number of XRef Package Explorers that can be invoked depends on the structure and contents of your Tcl source code.

Jumping to the Package Source Code

At some point when invoking multiple XRef Package Explorers, the lowest level of code is reached. At this point, you can jump to the actual source file where the package is declared. To jump to the source file:

  1. Select the desired file name.
  2. Click the Open button. If the Komodo editor is installed, the source file opens in Komodo. Otherwise, the file opens in the XRef Component Source Code Viewer.
  3. Within the source file, navigate to the line of code specified in the XRef Package Explorer.
Top

Files Tab

The Files tab displays the Tcl files used in the scanned Tcl source code. Files are presented in a collapsible tree that can be expanded to drill down into the commands, variables and namespaces used within a particular file. Click the Files column to sort file names in either ascending or descending order.

  • The icon denotes a file component.

Filtering Files

To filter files:

  1. Click the Filter button. The Filter Files screen appears.
  2. Enter the filter condition in the Files text box.
  3. Select a filter action:
    • Click Ok to enable and close the filter.
    • Click Apply to enable the filter. The filter screen stays open.
    • Click Cancel to abort and close the filter.

Opening File Details

Use the Open button to view details on a particular file. This button opens the selected file in a code editor. See Jumping to the File Source Code for more information.

Alternatively, drill down into a file list, using the expanding and collapsing tree nodes, to display the packages, namespaces, commands, and variables used in a particular file. Using the Open button with one of these components invokes an XRef Component Explorer window specific to that code component. For example, opening a variable component launches an XRef Variable Explorer. To open the details of one of these components, see:

Jumping to the File Source Code

To jump to the file's source code:

  1. Select the desired file name.
  2. Click the Open button. If the Komodo editor is installed, the source file opens in Komodo. Otherwise, the file opens in the XRef Component Source Code Viewer. Note: Double-clicking the file name also launches the source file into a viewer.
Top

Namespaces Tab

The Namespaces tab alphabetically displays all namespaces used and defined within the scanned Tcl source code. The #Definitions and #Uses columns display the number of times each namespace is used within the scanned Tcl source code. Click a column title to sort namespace content in ascending or descending order. The current sort column selected is shaded pink.

Initially, the Cross Reference Tool explorer only displays the global namespace '::' in the component display. The global namespace is the parent node of all namespaces organized within a collapsible tree. Expand the global node to view all namespaces under the parent namespace. Further expand a particular namespace node to view all commands and variables nested within the scope of that namespace.

  • The icon denotes a namespace component.

Filtering Namespaces

To filter namespaces:

  1. Click the Filter button. The Filter Namespaces screen appears.
  2. Enter the filter conditions, based-on any combination of the following:
    • Namespace: The name of the namespace.
    • #Definitions: Number of times the namespace is defined.
    • #Uses: Number of times the namespace is used.
  3. Select a filter action:
    • Click Ok to enable and close the filter.
    • Click Apply to enable the filter. The filter screen stays open.
    • Click Cancel to abort and close the filter.

Opening Namespace Details

Use the Open button to view details on a particular namespace, such as the name of the file where the namespace exists. Opening namespace details invokes an XRef Namespace Explorer window, which displays lower-level code details specific to the namespace selected. To open a namespace's details in an XRef Namespace Explorer window:

  1. Select the desired namespace.
  2. Click the Open button. An XRef Namespace Explorer window appears. This explorer is titled 'XRef Namespace: [::namespace_name]'. Note: Alternatively, double-click the namespace name to invoke and XRef Namespace Explorer.

The XRef Namespace Explorer displays the namespaces, commands, and variables that are within the scope of the selected namespace component. These components are accessible though toggling these component tabs. The Uses and Definition tabs list the files that are within the scope of this namespace. Both the Uses and Definitions tabs contain the following columns:

  • File column: The file(s) where the namespace is used or defined.
  • Line column: Provides the source-code line number where the package is used or defined.
  • Objects? column: Displays 'yes' if objects are defined within the specified location, otherwise, 'no'.
  • Begin column: The number of bytes in the file before the namespace definition.
  • Size column: The length of the definition in bytes.

This combination of XRef Namespace Explorer tabs and columns are useful for obtaining very low-level details on the components within the selected namespace.

It is possible to invoke numerous XRef Namespace Explorers while inspecting the scanned database. To continue exploring namespace component details, click the Open button once again. The total number of XRef Namespace Explorers that can be invoked depends on the structure and contents of your Tcl source code.

Alternatively, drill down into a namespace list, using the expanding and collapsing tree nodes, to display the commands and variables within the scope of a particular namespace. Using the Open button with one of these components invokes an XRef Component Explorer window specific to that code component. To open the details of one of these components, see:

Show Parent Namespace

Use the Show parent namespace button to invoke an XRef Namespace Explorer that displays the parent namespace of the current namespace. To view the parent namespace of the current namespace:

  • Click the Show parent namespace button. An XRef Namespace Explorer appears. The title of this explorer follows the pattern: 'XRef Namespace: [::namespace_name]'.

Note: The global namespace '::' does not have a parent.

Jumping to the Namespace Source Code

At some point when invoking multiple XRef Namespace Explorers, the lowest level of code is reached. At this point, you can jump to the actual source file where the namespace either used or defined. To jump to the source file:

  1. Select the desired namespace name.
  2. Click the Open button. If the Komodo editor is installed, the source file opens in Komodo. Otherwise, the file opens in the XRef Component Source Code Viewer.
  3. Within the source file, navigate to the line of code specified in the XRef Namespace Explorer.
Top

Commands Tab

The Commands tab alphabetically displays all commands used and defined within the scanned Tcl source code. The #Definitions and #Uses columns display the number of times each command is used within the scanned Tcl source code. Click a column title to sort command content in ascending or descending order. The current sort column selected is shaded pink.

Commands are presented in a collapsible tree that can be expanded to drill down into the variables used and defined within a particular command.

  • The icon denotes a command component.

Filtering Commands

To filter commands:

  1. Click the Filter button. The Filter Commands screen appears.
  2. Enter the filter conditions, based-on any combination of the following:
    • Name: Command name.
    • #Definitions: Number of times the command is defined.
    • #Uses: Number of times the command is used.
  3. Select a filter action:
    • Click Ok to enable and close the filter.
    • Click Apply to enable the filter. The filter screen stays open.
    • Click Cancel to abort and close the filter.

Opening Command Details

Use the Open button to view details on a particular command, such as the variables used within the command. Opening a command's details invokes an XRef Command Explorer window, which displays lower-level code details specific to the command selected. To open command details in an XRef Command Explorer window:

  1. Select the desired command.
  2. Click the Open button. An XRef Commands Explorer window appears. This explorer is titled 'XRef Command: [command_name]'. Note: Alternatively, double-click the command name to invoke an XRef Command Explorer.

Alternatively, drill down into a command list, using the expanding and collapsing tree nodes, to display the variables defined and used within a particular command. See, Opening Variable Details for more information.

The XRef Command Explorer displays the variables that are used and defined within the selected command component. Variable components are accessible though toggling to the Variable tab. Toggle between the Uses and Definitions tabs to view what files are used and where those files are defined. The Definitions tab contains the following columns:

  • File column: The file(s) where the command is defined.
  • Line column: Provides the source-code line number where the command is defined.
  • Type column: The component type (command or variable).
  • Prot column: Component protection level. For example, 'public'.
  • Scope column: The scope of the command.
  • Origin? column: Displays the name of the command at its original location if imported into a namespace. Displays the initial name of the command if renamed.

This combination of XRef Command Explorer tabs and columns is useful for obtaining low-level details on the components within the selected command. It is possible to invoke numerous XRef Command Explorers while inspecting the scanned database. To continue exploring command component details, click the Open button once again. The total number of XRef Command Explorers that can be invoked depends on the structure and contents of your Tcl source code.

Show Execution Namespace

Use the Show execution namespace button to invoke an XRef Command Explorer, which displays the parent namespace of the current command. To view the parent namespace of the current command:

  • Click the Show execution namespace button. An XRef Command Explorer appears.

Note: The global namespace '::' does not have a parent.

Show Origin of the Command

Use the Show origin button to show the origin of the command.

  • Click the Show origin button. An XRef Command Explorer appears displaying the origin of the command.

Jumping to the Command Source Code

At some point when invoking multiple XRef Command Explorers, the lowest level of code is reached. At this point, you can jump to the actual source file where the command is declared. To jump to the source file:

  1. Select the desired command name.
  2. Click the Open button. If the Komodo editor is installed, the source file opens in Komodo. Otherwise, the file opens in the XRef Component Source Code Viewer.
  3. Within the source file, navigate to the line of code specified in the XRef Command Explorer.
Top

Variables Tab

The Variable tab alphabetically lists all variables used and defined within the scanned Tcl source code. The #Definitions and #Uses columns display the number of times each variable is used. This tab provides the lowest-level view of the database. For this reason, variables are presented in a flat list and cannot be expanded for drilling further down into the code.

  • The icon denotes a variable component.

Filtering Variables

To filter variables:

  1. Click the Filter button. The Filter Variables screen appears.
  2. Enter the filter conditions, based on any combination of the following:
    • Scope: Variable scope.
    • Name: Variable name.
    • #Definitions: Number of times the variable is defined.
    • #Uses: Number of times the variable is used.
  3. Select a filter action:
    • Click Ok to enable and close the filter.
    • Click Apply to enable the filter. The filter screen stays open.
    • Click Cancel to abort and close the filter.

Opening Variable Details

Use the Open button to view details on a particular variable, such as the files containing the variable definitions. Opening a variable's details invokes an XRef Variable Explorer window, which displays lower-level code details specific to the variable selected. To open a variable's details in an XRef Variable Explorer window:

  1. Select the desired variable.
  2. Click the Open button. An XRef Variable Explorer window appears. This explorer is titled 'XRef Variable: [namespace :: variable_name]'. Note: Alternatively, double-click the variable name to invoke an XRef Variable Explorer.

The XRef Variable Explorer displays the files where the selected variable is used and defined. Toggle between the Uses and Definitions tabs to view the all the files where the variable is used and defined. The Definitions tab contains the following columns:

  • File column: The file(s) where the variable is defined.
  • Line column: Provides the source-code line number where the variable is defined.
  • Type column: The variable definition type.
  • Origin column: Displays the name of the variable at its original location if imported into a namespace or procedure scope.
  • Callers? column: Commands that call the procedure the specified variable belongs to. This is only for variables imported into a procedure scope via [upvar].

Show Defining Scope of the Variable

Use the Show defining scope button to invoke an XRef Variable Explorer, which displays the namespace or procedure the variable is defined in. To view the namespace or procedure scope of the variable:

  • Click the Show defining scope button. An XRef Variable Explorer appears.

Note: The global namespace '::' does not have a parent.

Show Origin of the Variable

Use the Show origin button to show the origin of the variable.

  • Click the Show origin button. An XRef Variable Explorer appears displaying the origin of the variable.

Jumping to the Variable Source Code

To jump to a variable's source code:

  1. Select the desired file where the variable is used or declared.
  2. Click the Open button. If the Komodo editor is installed, the source variable opens in Komodo. Otherwise, the variable opens in the XRef Component Source Code Viewer. Note: Double-clicking the variable name also launches the source file into a viewer.
Top

Building a Cross Reference Tool Database

The Cross Reference Tool builds component databases by scanning the Tcl source contained in the specified input. Use File | Save to store the extracted component information in a database. Cross Reference Tool database files have a ".txr" extension. There are two approaches to building a database for use with the XRef tool. These include:

  1. Specifying Tcl Source Code Files
  2. Specifying Projects and Packages

Specifying Tcl Source Code Files

The XRef Tool can extract Tcl program component information from various Tcl source files. On the command-line, specify the input as follows:

Windows

  • Command Line: tclxref.exe -scan dbfile.txr file1.tcl file2.tcl ...
    Where dbfile is the name of the database file used to store the extracted component information.

Unix

  • Shell Prompt: tclxref -scan dbfile.txr file1.tcl file2.tcl ...
    Where dbfile is the name of the database file used to store the extracted component information.

Specifying Projects and Packages

The Cross Reference Tool can extract program component information from programs and packages contained in TclApp (or Prowrap) projects, Tcl Dev Kit Package definitions (".tap" files), and from Komodo project files. Use the Windows File Menu, command line, or the Unix shell prompt as follows:

Windows

File Menu:

  • TclApp Projects: File | Scan files for database | Tcl Dev Kit TclApp/Prowrap project
  • Package Definitions: File | Scan files for database | Tcl Dev Kit Package Definition
  • TEApot Package Definitions: File | Scan files for database | TEApot meta data
  • Komodo Project Files: File | Scan files for database | Komodo project

Command Line:

  • TclApp Projects: tclxref.exe -tpj tclapp.tpj
  • TAP Package Definitions: tclxref.exe -tap package.tap
  • TEApot Package Definitions: tclxref.exe -teapot teapot.txt
  • Komodo Project Files: tclxref.exe -komodo project.kpf

Unix

Shell Prompt:

  • TclApp Projects: tclxref -tpj tclapp.tpj
  • TAP Package Definitions: tclxref -tap package.tap
  • TEApot Package Definitions: tclxref -teapot teapot.txt
  • Komodo Project Files: tclxref -komodo project.kpf

Opening a Database

Use the following commands to load a database file into an XRef explorer window. XRef tool database files have a ".txr" extension.

Windows

  • File Menu: File | Open database
  • Command Line: tclxref.exe -gui dbfile
    Where dbfile is the name of the database file used to store the extracted component information.

Unix

  • File Menu: File | Open database
  • Shell Prompt: tclxref -gui dbfile.txr
    Where dbfile is the name of the database file used to store the extracted component information.

Opening a Database in a New Window

To open a database file in a new XRef explorer window:

Windows

  • File Menu: File | Open database in new window

Closing a Database

To close a Tcl database file:

Windows

  • File Menu: File | Close
Top