Where Tcl Runs: Standalone and Embedded

Part I · Module 1 · Chapter 1.3 · Where Tcl Runs: Standalone and Embedded

1. The Problem This Prevents

Imagine opening a colleague's Tcl script and reading this:

set threshold 5
foreach item [report_status -all] {
    puts "checking $item"
}

Four commands: set, foreach, report_status, puts. Three of them are Tcl. One of them is not Tcl at all and will not work on your machine, in tclsh, or in any other application. Nothing about how it is written tells you which one.

If you do not have a model for that, you will eventually spend an afternoon trying to work out why a "Tcl script" fails with invalid command name, reading Tcl documentation that was never going to mention the command. The model takes ten minutes to install and saves that afternoon permanently.

2. Deployment One: Tcl as the Program

The straightforward case. You install Tcl, and you get a program — conventionally tclsh — whose job is to run Tcl.

tclsh script.tcl

Here, Tcl is the application. What you have available is the language plus its standard command set: puts, set, string, list, file, expr, proc, and the rest of the roughly ninety commands Chapter 1.1 §4 counted.

That set is defined by the Tcl release, not by anybody's product. A script using only those commands runs under tclsh on Linux, macOS, or Windows, and inside any correctly built Tcl interpreter anywhere. This is portable Tcl, and it is the whole of what Part I teaches.

3. Deployment Two: Tcl Inside a Host Application

The second case is the one Chapter 1.1 §6 said the language was designed for.

An application links the Tcl interpreter into itself as a component. On startup, it registers commands of its own into the same command table that already holds puts and if. From that point, a user typing at that application's prompt is writing Tcl — real Tcl, with real foreach and real set — in an interpreter whose vocabulary is larger than standard Tcl's.

The application's commands are implemented in the application's own code. They do things only that application can do: query its internal data, change its settings, run its operations.

The two rows share a middle component. That is the point of the figure: it is not a Tcl-like language in the bottom row, it is the same interpreter.

4. Why You Cannot Tell by Looking

A command registered by a host application is not marked in any way. It has no prefix the language enforces, no namespace it is required to live in, no different calling convention. It is looked up in the same table, by the same mechanism, as puts.

Return to §1 with that in mind:

foreach item [report_status -all] {
    puts "checking $item"
}

foreach and puts are standard. report_status is invented for this chapter, and in the real world would be something a particular product defined. Syntactically they are peers. The only way to tell them apart is to know, or to ask.

5. Which Commands Are Really Tcl's?

A practical rule of thumb, before the precise technique in §6.

Standard Tcl commands are overwhelmingly short, lowercase, and generic: set, puts, expr, list, lindex, string, file, open, proc, foreach, info, catch, regexp. They describe general computing operations, because they have to apply to every program ever written in Tcl.

Host application commands tend to be longer, domain-specific, and often verb-underscore-noun: a name like report_status or write_output is describing an operation that only makes sense inside one product.

This is a useful heuristic and nothing more. It is a convention, not a rule the language enforces, and plenty of exceptions exist. Treat it as a reason to check, not as the check itself.

6. The Technique: Ask the Interpreter

info commands does not only count commands, as Chapter 1.1 used it. Given a name, it returns that name if such a command exists, and an empty string if it does not.

That is a question you can put to any Tcl prompt:

puts "puts          -> [info commands puts]"
puts "report_status -> [info commands report_status]"

Run under tclsh:

puts          -> puts
report_status ->

The first line found a command and echoed its name. The second found nothing and returned empty. Run the identical script inside an application that defines report_status, and the second line would print report_status.

This is worth internalising as a habit, because it works everywhere and needs no documentation. When you do not know whether a command is Tcl's, ask the interpreter you are sitting in, then ask a plain tclsh the same question. If tclsh does not have it, it is not Tcl.

7. Why Engineers Meet the Embedded Case Constantly

A brief word on motivation, since it explains why this track exists.

Semiconductor design and verification tools adopted embedded Tcl broadly. Synthesis, static timing analysis, place-and-route and simulation tools are commonly driven by a Tcl interpreter with hundreds of product-specific commands registered into it. An engineer automating that work is writing Tcl all day without necessarily having learned Tcl, which is exactly how the "Tcl is confusing" reputation forms — they are mostly meeting someone's command set, not the language.

Two consequences follow, and both are worth having now:

1. The language is worth learning on its own terms. The foreach, set, string and file parts of those scripts are standard Tcl and transfer everywhere, which is why Part I teaches them with tclsh and ordinary files rather than inside a tool.
2. The product commands are not portable, and not even consistent between vendors. Two tools solving the same problem routinely use different command names, different options, and different return values. A script is written against a specific tool and version, and pretending otherwise is how a flow breaks on a tool upgrade.

None of that is a prerequisite for Part I. Part I needs tclsh and a text editor. Part II is where tool command sets belong, and it opens by naming this boundary explicitly before using a single one of them.

8. The Discipline to Adopt Now

Carry one question for the rest of this track:

Is this command part of Tcl, or part of the thing I am running Tcl inside?

Three reasons it pays off immediately:

• Reading. You will stop looking for report_status in Tcl documentation.
• Debugging. invalid command name stops being mysterious. It usually means right script, wrong interpreter.
• Writing. When you write something reusable, you will notice that mixing the two makes it tool-specific, and you can decide whether you meant to.

9. Exercises

Exercise 1 — interrogate your own interpreter. Save which-commands-exist.tcl from §6 and run it. Then add lines asking about foreach, lindex, and a name you have invented. Confirm that invented names come back empty.

Exercise 2 — classify without running. For each name, say whether you would expect it to be standard Tcl or a host application's, and give your reason from §5: lsort, load_project, string, set_option, clock, open.

Then check the ones you can: run info commands <name> for each under tclsh. Which of your guesses were wrong? The heuristic in §5 is imperfect by design, and finding out where it fails is the point.

Exercise 3 — explain the failure. A colleague sends you a script that works for them and fails for you with invalid command name "write_output". Write the two-sentence explanation you would reply with, and the one question you would ask them.

Exercise 4 — the honest limit. info commands tells you whether a command exists in the interpreter you asked. Explain why that still does not tell you whether the command is standard Tcl, and what second check §6 adds to settle it.

10. Summary

• Tcl is deployed two ways: as the program itself, conventionally tclsh, or embedded as a component inside a host application.
• Standalone Tcl gives you the standard command set — around ninety generic commands, defined by the Tcl release and portable everywhere.
• An embedded interpreter has those plus the host's own commands, registered into the same table at startup.
• Host commands are indistinguishable by syntax. No prefix, no namespace, no different calling convention.
• info commands <name> returns the name or an empty string. Ask the interpreter you are in, then ask a plain tclsh — if tclsh lacks it, it is not Tcl.
• Short and generic suggests standard; long, domain-specific, verb-underscore-noun suggests a host command. A heuristic, not a rule.
• Host commands are not portable between products or versions. Standard Tcl is.
• Part I is standalone Tcl only. You need tclsh and a text editor, nothing more.

Having established that tclsh is where Part I lives, the next chapter makes sure you actually have it, can find it, and know which version you are holding.