Tcl · Module 27

Helpers You Source at the Prompt

The tool console is a Tcl prompt, so the repetitive part of debugging is a procedure you have not written yet. These are optimised for typing, which makes them the opposite of flow code.

Intermediate19 min readtcledapart-iiinfrastructuredebuginteractive

Part II · Module 27 · Chapter 27.2 · Helpers You Source at the Prompt

Chapter 27.1 was about running without a human. This chapter is the opposite case: a human at the tool's prompt, doing the same four things over and over.

Those four things are procedures nobody has written yet.

1. What the prompt is actually for

Debugging a timing or physical-design problem is a loop: ask what the worst paths are, look at one, ask what clock reaches it, ask where an instance is, go back.

Each of those is a tool command with options you half-remember, producing more output than you wanted. So people retype a long command, scroll, retype it with a different filter, and lose the earlier answer. The session is productive for about the first ten minutes.

The fix is a file of small procedures you source when a session starts. The tool console is a Tcl interpreter (Chapter 17.1), so this is not a feature you are waiting for.

2. A real session

The transcript below is a real interactive session over a pty — expect spawned a genuine tclsh, sourced the helper file, and typed the commands. Everything from the first prompt onward is verbatim.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

% source /private/tmp/m27/flow/cfg/demo.tcl
created scan_clk
% h
  v ?n?    the worst n violators (default 5)
  c        the clocks and their periods
  f pat    find an endpoint by glob
  h        this list
% v
  u_dec/sel_reg_2/D           -0.1310  max_delay
  u_mem/addr_reg_7/D          -0.0730  max_delay
  u_io/u_sync/sync_reg_1/D    -0.0310  min_delay
  u_ctrl/state_reg_0/D        -0.0210  max_delay
4 of 5 shown
% v 2
  u_dec/sel_reg_2/D           -0.1310  max_delay
  u_mem/addr_reg_7/D          -0.0730  max_delay
2 of 5 shown
% c
  core_clk     5.00 ns
  io_clk      10.00 ns
  scan_clk    20.00 ns
3 clock(s)
% f u_mem/*
  u_mem/addr_reg_7/D
  u_mem/dout_reg_3/D
2 match(es) for 'u_mem/*'
% exit

Four helpers, each one word. v for violators, c for clocks, f for find, h for help.

3. Why one-letter names are correct here

This is the part that looks wrong, because it contradicts the advice that applies everywhere else in this track.

Flow code is read far more than it is written. A prompt helper is typed far more than it is read.

Chapter 10.10 argues for names that say what a procedure does, and that is right for create_clock_if_missing — a name read by everyone who maintains the flow and typed roughly once.

v is typed forty times in an afternoon by the person who wrote it, while looking at something else, and read approximately never. Optimising it for reading costs forty keystrokes an hour and buys nothing.

So the two bodies of code have opposite naming rules, and the boundary between them is the file they live in:

	Flow code	Prompt helper
Typed	once	dozens of times a day
Read	by everyone, for years	by its author, rarely
Name	`create_clock_if_missing`	`c`
Lives in	`flow/lib/`	`flow/cfg/`, sourced on demand

The mistake people actually make is applying the rule backwards — long names at the prompt, where it is just friction, and short names in the flow, where it is a maintenance problem. Knowing which body of code you are writing is the whole decision.

And the consequence of that boundary: a flow script must never depend on a prompt helper. If v is useful enough that a flow wants it, it belongs in flow/lib/ with a real name, and the prompt file can define v as a one-line alias to it.

4. The helper nobody writes

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# h — what helpers exist. A helper set you cannot enumerate is a helper set
# nobody uses.
proc h {} {
    puts "  v ?n?    the worst n violators (default 5)"
    puts "  c        the clocks and their periods"
    puts "  f pat    find an endpoint by glob"
    puts "  h        this list"
    return ""
}

A set of one-letter procedures is unusable by anyone who did not write it, and unusable by its author three months later. h is what makes it shareable — and it costs four lines.

This is the same argument as Chapter 25.3 §4's rules-with-reasons and Chapter 26.4 §3's pruning-with-reasons: the thing that makes a convenience into infrastructure is that it can explain itself.

The honest weakness is that h is hand-maintained, so it goes stale. A version that derives itself is possible:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc h {} {
    foreach p [lsort [info procs ::?]] {
        puts [format "  %-8s %s" [namespace tail $p] [info args $p]]
    }
}

info procs ::? matches single-character procedure names at the global level, and info args gives each one's parameters (Chapter 14.10). That cannot go stale — and it also cannot say what any of them is for, which is the thing you actually needed. Neither version is strictly better; the hand-written one is worth the staleness as long as somebody notices.

5. What the transcript shows about the prompt itself

Look at the first two lines again:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

% source /private/tmp/m27/flow/cfg/demo.tcl
created scan_clk

source printed created scan_clk. Nothing in the file printed that — it is the return value of the last command in the sourced file, which tclsh echoes because an interactive prompt displays any non-empty result.

Two things follow.

A sourced file's last command leaks its result to the prompt. Harmless here; noisy if the last command returns a 400-element list, which is why a setup file often ends with an explicit return "" or a deliberate summary line.

It is an argument for helpers that return a summary. Every helper in the transcript ends with one — 4 of 5 shown, 3 clock(s), 2 match(es) for 'u_mem/*'. Those are not decoration: the prompt displays them for free, and they carry the denominator that Chapter 22.7 has been insisting on since Module 22. v showing four rows out of five tells you one path was not a violation; four rows alone does not.

Note also v printing 4 of 5 rather than 5: the fifth row has positive slack, so the loop stops at the first non-violation after sorting. A helper that silently shows fewer rows than you asked for must say so, or you will read the short list as "that is all of them".

6. What a prompt helper must not do

Honest limits, because this is the file where discipline is weakest — it is "just" debug code.

It must not write state the flow depends on. A helper that sets a global, defines a clock or changes a variable makes the session unreproducible: the next command behaves differently and nothing records why. Debug helpers read; flow code writes.

It must not be required. If the flow breaks when flow/cfg/ is absent, those helpers are flow code living in the wrong directory.

It must not shadow a tool command. c is safe; f is safe; a helper called report_timing or set is a trap that will fire in six months, in a session where somebody is debugging something else. info commands <name> before choosing a name costs nothing (Chapter 25.1 §4).

It must tolerate being sourced twice. Sourcing a helper file over itself must be harmless, which is Chapter 27.7's subject — and for a file of pure proc definitions it already is, because redefining a procedure replaces it.

The shadowing risk is the one that bites hardest, because the failure is silent and delayed.

Tcl lets you redefine any command, including its own built-ins. A debug file that defines proc filter {...} in the global namespace replaces whatever filter meant — and in a tool whose command set you did not write (Chapter 25.1), you cannot know what you have replaced by reading your own file.

Two defences, and both are cheap. Put the helpers in a namespace and expose only the short aliases you want. And check before defining:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

foreach name {v c f h} {
    if {[llength [info commands ::$name]]} {
        puts stderr "warning: redefining existing command '$name'"
    }
}

That is the idempotency check of Chapter 27.7 applied to names rather than to state, and it is the difference between a helper file that is safe to source into an unfamiliar tool and one that is not.

7. Exercises

Exercise 1. Why is the repetitive part of interactive debugging a procedure nobody has written?

Exercise 2. Why are one-letter names correct at the prompt and wrong in flow code?

Exercise 3. What mistake do people actually make about those two naming rules?

Exercise 4. What is the rule about a flow script depending on a prompt helper?

Exercise 5. Why is h worth four lines?

Exercise 6. Give the trade-off between a hand-written h and one derived from info procs.

Exercise 7. Why did source demo.tcl print created scan_clk?

Exercise 8. Why does every helper return a summary line?

Exercise 9. v showed 4 of 5 rows. Why must it say so?

Exercise 10. Why is shadowing a tool command the most dangerous mistake in a helper file?

Answers.

1. Because the tool console is a Tcl interpreter, so anything you retype is something you could have defined once. Nothing is being waited on.

2. Because the two bodies of code are optimised for different things. Flow code is read by everyone for years and typed once, so it wants descriptive names. A prompt helper is typed dozens of times a day by its author and read almost never.

3. They apply them backwards — long names at the prompt, where it is pure friction, and short names in the flow, where it becomes a maintenance problem.

4. It must never. If the flow needs it, it belongs in the shared library with a real name, and the prompt file can alias it.

5. Because a set of one-letter procedures is unusable by anyone who did not write it, and by its author a few months later. h is what turns a convenience into something shareable.

6. The derived version cannot go stale but cannot say what anything is for; the hand-written one says what matters and goes stale. The hand-written one is worth it as long as somebody notices.

7. Because an interactive prompt echoes any non-empty result, and that was the return value of the last command in the sourced file — not something the file printed.

8. Because the prompt displays it for free, and it carries the denominator. "4 of 5 shown" tells you something that four rows alone does not.

9. Because the fifth row was not a violation, so the list is shorter than requested. Without saying so, a short list reads as "that is all of them".

10. Because Tcl lets you redefine any command including built-ins, the failure is silent, and it arrives months later in a session about something else — and in an unfamiliar tool you cannot tell what you replaced by reading your own file.

Remember.

The tool console is a Tcl prompt, so anything you retype is a procedure you have not written.
One-letter names are correct at the prompt — typed dozens of times a day, read almost never — and wrong in flow code, which is the reverse.
The common mistake is applying those rules backwards.
A flow script must never depend on a prompt helper. If it needs one, the helper belongs in the shared library with a real name.
Write h. A helper set that cannot enumerate itself is one nobody else uses.
An interactive prompt echoes the last result, so a sourced file leaks its final command's return value.
Make every helper return a summary with its denominator — the prompt prints it for nothing.
Say when you showed fewer rows than asked, or a short list reads as a complete one.
Debug helpers read; flow code writes. A helper that changes state makes the session unreproducible.
Check info commands before taking a name. Redefining a tool command fails silently, months later.

Where this fits

Part of the Tcl curriculum.