Every GUI Action Is a Logged Tcl Command

Part II · Module 17 · Chapter 17.3 · Every GUI Action Is a Logged Tcl Command

A common assumption is that the GUI and scripting are two ways of using a tool, and you pick one. That is not how these tools are built.

The GUI is a front end to the same interpreter. When you click something, the tool issues a Tcl command — the same command you could have typed — and in nearly every case it writes that command to a log.

Which means the GUI is not an alternative to scripting. It is the fastest way to find out what to write.

1. Why it works this way

Chapter 16.1 explained that the tool's functionality is exposed as commands in an embedded interpreter. The GUI is built on that same command set — it has no private back door to the design database, because the command layer is the interface.

So a menu item that sets a clock period has to call the same constraint command you would call. Having arrived there, recording what it called costs the tool almost nothing, and it is how you find out what happened.

2. The command log

Every major tool keeps a transcript of the commands a session executed — GUI-issued and typed alike. The details vary: the file name, where it is written, whether there is a transcript pane in the GUI, and what the tool calls it.

Rather than guess at names I cannot check, here is how to find it in whatever tool you are using:

• Look for a transcript, command log or history pane in the GUI.
• Check the working directory after a session for a file whose name contains command, log, history or transcript.
• Search the tool's own help for those words — Chapter 17.6.
• Ask the interpreter: info commands *transcript*, info commands *log* — the discovery technique from Chapter 17.1 §3.

Finding it once, in each tool you use, pays for itself permanently.

3. The mechanism, built and running

No EDA GUI is involved below. Instead, here is the mechanism itself — and it is worth seeing, because it explains why a transcript exists at all and what it can and cannot contain.

A tool logs commands with an execution trace: the feature from Chapter 14.12 §6. Attach one to a command and you are told every time it runs, with its arguments.

# A command transcript, built the way a tool builds one.
proc start_transcript {path commands} {
    set ::TRANSCRIPT [open $path w]
    foreach c $commands {
        trace add execution $c enter ::log_invocation
    }
    return $path
}

proc log_invocation {cmdstring op} {
    puts $::TRANSCRIPT $cmdstring
    flush $::TRANSCRIPT
}

proc stop_transcript {} { close $::TRANSCRIPT }

Now run some commands — imagine these came from clicking around:

start_transcript session.log {read_design get_cells get_ports report_area current_design}

read_design cpu.design
current_design
get_cells u_*
get_ports data_*
report_area

stop_transcript

And the log:

  --- session.log now contains: ---
read_design cpu.design
current_design
get_cells u_*
get_ports data_*
report_area

Every invocation, with its arguments, in order. That is a tool transcript — a real one differs in scale and in being implemented inside the tool, not in what it is.

4. The payoff: the log is already a script

The log is a sequence of valid commands, so it runs:

  replaying session.log as a script:
    line 1 ok: read_design cpu.design
    line 2 ok: current_design
    line 3 ok: get_cells u_*
    line 4 ok: get_ports data_*
    line 5 ok: report_area
  replayed 5 commands

Five for five. And turning it into something worth keeping needs only the step from Chapter 17.2 §1 — adding the output calls, because a script echoes nothing:

source toolshell.tcl
read_design cpu.design
puts "design    : [current_design]"
puts "cells u_* : [get_cells u_*]"
puts "ports     : [get_ports data_*]"
puts "area      : [report_area]"

design    : cpu_top
cells u_* : u_fifo u_alu u_ctrl u_decode
ports     : data_in data_out
area      : cells: 4

That is the whole workflow: click, read the log, keep what worked, add the output.

5. Using it well

The transcript is a discovery tool, not a source of finished scripts. Four things to do with what you find.

Look up what you copied. The log tells you the command and the options the GUI chose. It does not tell you what they mean, whether there is a better option, or which arguments were defaults. Read the reference for anything you keep — Chapter 17.6.

Delete the noise. A GUI session logs everything, including the clicking around that went nowhere, redundant re-queries, and view changes with no effect on the design. A ten-minute session might yield four lines worth keeping.

Replace literals with variables. The GUI logs what you actually did, so paths, block names and values are hard-coded. Those become argv and configuration — Chapter 15.3 and 15.5.

Add the structure. A transcript is a flat list of commands with no error handling, no validation and no exit status. Wrapping it in the shape from Chapter 15.9 is what turns it into something another engineer can run.

6. When the GUI is genuinely the right tool

None of this makes the GUI useless. It is the better choice for:

• Looking at things — a schematic, a layout, a waveform, a critical path drawn on the design. No script output substitutes for seeing it.
• Finding the command for something you do not know how to express — the subject of this chapter.
• One-off investigation where you will never repeat the steps.

It is the wrong choice for anything repeated, anything another person must run, and anything whose result is recorded — because clicks are not reviewable, not version-controlled, and not reproducible. That is Chapter 17.2 §6's console-versus-file distinction, one level up.

The productive habit is to use both for what each is good at: explore in the GUI, read the log, write the script.

7. Exercises

Exercise 1. Why does clicking a menu item produce a Tcl command?

Exercise 2. What Tcl feature underlies a command transcript?

Exercise 3. A transcript records the command and its arguments. What does it not record, and why does that matter?

Exercise 4. Name two ways to find the command log in a tool you have not used before.

Exercise 5. You copy ten logged lines into a script and it produces no output. Why?

Exercise 6. Give two reasons not to replay a transcript as a production flow script.

Exercise 7. Name two things the GUI is genuinely better at than a script.