tclsh: Finding and Checking the Interpreter

Part I · Module 1 · Chapter 1.4 · tclsh: Finding and Checking the Interpreter

1. Is It There At All?

Chapter 1.3 established that Part I lives in standalone Tcl, and that the standalone interpreter is conventionally a program called tclsh. First question: do you have it?

In your terminal — your ordinary operating-system shell, not a Tcl prompt — ask where the program is:

which tclsh

/usr/bin/tclsh

A path means the program exists and your shell can find it. If instead you get nothing back, or tclsh not found, skip to §6.

2. The Version Question, and Why the Obvious Form Fails

If you have used almost any other command-line tool, your instinct is:

tclsh --version

Try it. Here is what happens, and it is worth seeing rather than being told:

(nothing at all — no version, no error)

No version, no error, and an exit status of zero as though it had succeeded.

Worse, if you run it on a real terminal, it does not return you to your shell at all — it drops you into Tcl's interactive prompt:

%

The reason is simple once stated. tclsh has no --version option. It expects the name of a script to run, and with no script to run it does the other thing it knows how to do, which is read commands interactively. Your --version was not rejected; it was simply not a script name, so it never became one.

3. The Question That Works: Ask Tcl, Not the Program

The version is a property of the Tcl library, so ask Tcl itself. Two commands report it, and they are not the same:

puts [info tclversion]
puts [info patchlevel]

8.5
8.5.9

• info tclversion gives the major and minor version — 8.5, 8.6, 9.0. This is the number that decides which features exist.
• info patchlevel gives the full release including the patch — 8.5.9. This is the number to quote in a bug report.

You can ask without creating a file at all, by piping one command into tclsh:

echo 'puts [info patchlevel]' | tclsh

8.5.9

That one-liner is the practical version check, and it is worth remembering in place of the --version habit.

4. What the Version Number Decides

This track is written against Tcl 8.6, which is the broadly portable modern baseline. Everything in Module 1 works on 8.5, 8.6 and 9.0 alike — nothing on this page or the next five depends on your version.

It starts to matter later, because 8.6 added commands that Part I uses:

The specific places 8.6 is required, so you are not surprised:

• try / finally — the structured error handling in Module 14. The older catch command works everywhere and is taught alongside it, so an 8.5 interpreter is not a dead end.
• lmap — the list-transforming loop in Module 9. A foreach with lappend does the same job on 8.5.

5. The Generic Name Usually Points at a Specific Version

One detail that explains a surprising amount of confusion on shared machines. tclsh is frequently not a program at all, but a link to a versioned one:

ls -l /usr/bin/tclsh

/usr/bin/tclsh -> tclsh8.5

So tclsh means "whichever Tcl this machine has nominated as the default", and tclsh8.6 — if present — means that specific one. Both may exist:

ls /usr/bin/tclsh*

/usr/bin/tclsh    /usr/bin/tclsh8.5

Two practical consequences:

1. tclsh can change under you. A system update that moves the link changes which Tcl your scripts run on, without any script changing.
2. If you need a specific version, name it. Running tclsh8.6 script.tcl is explicit; running tclsh script.tcl is a request for the default.

For Part I, the default is fine. The habit is worth forming now because it is exactly the class of problem that makes a working flow break after a machine is upgraded.

6. If Nothing Was Found

tclsh not found means your shell searched the directories it knows and found no such program. That does not prove Tcl is absent from the machine — only that it is not somewhere your shell is looking.

In order, on an engineering system:

• Try the versioned names. which tclsh8.6, which tclsh8.5. Packages sometimes install only the versioned name.
• Ask whether a module system owns it. Shared engineering machines commonly hide tools behind an environment-module or equivalent mechanism, so the program only appears after it has been loaded. If your site has such a system, Tcl is very likely in it, and this is a one-line question to a colleague rather than an installation problem.
• Check whether a tool you already have ships one. Many large applications bundle a Tcl interpreter. That interpreter is a perfectly good tclsh for learning purposes, though note Chapter 1.3 §3 — if you run Tcl inside the application rather than its bundled tclsh, you will also have that application's own commands available, and should take care not to learn them as Tcl.
• Install it properly if the machine is yours. Tcl is open source and distributed through the usual channels for each platform; the project's own site at tcl.tk is the canonical starting point. Use your platform's normal package source rather than anything else, and if the machine is not yours, ask the person who owns it.

7. Exercises

Exercise 1 — find and version yours. Run which tclsh, then the one-liner from §3. Write down both the path and the patch level. You will want the version number again when you reach Module 9 and Module 14.

Exercise 2 — reproduce the silent failure. Run tclsh --version and watch it do nothing useful. If it opens a % prompt, type exit to leave. The point of doing this deliberately is that you will recognise it instantly if you do it by accident in six months.

Exercise 3 — the two version commands. Run both info tclversion and info patchlevel. Explain in one sentence which you would put in a bug report and why the other is the one a feature check uses.

Exercise 4 — look for a versioned twin. Run ls -l on the tclsh your which reported. Is it a link? If so, what does it point at? If your platform's listing works differently, the question to answer is the same: is tclsh a program, or a pointer to one?

Exercise 5 — predict a failure. Your interpreter reports 8.5. A later chapter offers lmap. Using §4, say what will happen when you run it and what you would use instead. You have not been taught either command; the answer is about version behaviour, not about lists.

8. Summary

• which tclsh answers whether the interpreter exists and where it is.
• tclsh --version does not report a version. tclsh has no such option, so it falls through to reading commands interactively — silently, with exit status zero.
• If you land at an unexpected %, type exit. That is Tcl's interactive prompt, not a fault.
• Ask Tcl instead: info tclversion for the feature-deciding number, info patchlevel for the exact release.
• The one-liner is echo 'puts [info patchlevel]' | tclsh. No file needed.
• This track targets 8.6. All of Module 1 runs on 8.5, 8.6 and 9.0; only try/finally and lmap later in Part I need 8.6, and both have 8.5 equivalents that are taught anyway.
• tclsh is often a link to a versioned program. Name the version explicitly when it has to be a specific one.
• info nameofexecutable settles which interpreter actually answered.

You have an interpreter and you know what it is. The next chapter uses it two ways — typing commands straight at the % prompt, and putting them in a file — and explains why only one of those is worth keeping.