Tcl · Module 17

Setup Files and Session Startup

Before your first line runs, the tool has already executed several files you did not write. When a script works for you and not for a colleague, the difference is almost always in one of them.

Intermediate17 min readtcledapart-iistartupconfigurationreproducibility

Part II · Module 17 · Chapter 17.4 · Setup Files and Session Startup

By the time you type your first command, the tool has already run code. Site defaults, project settings, your personal customisations — sourced automatically, in an order you did not choose, from files you may not know exist.

Most of the time this is helpful. The rest of the time it is the reason your script works and your colleague's identical script does not.

1. The one that is easiest to prove

tclsh has its own startup file, and its behaviour is the whole lesson in miniature.

Put this in ~/.tclshrc:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

puts "  startup file ran: .tclshrc"
set ::SITE_SETTING "from .tclshrc"
proc site_helper {} { return "a helper the startup file defined" }

Start an interactive session, and it runs:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  startup file ran: .tclshrc
% info exists ::SITE_SETTING
1
% site_helper
a helper the startup file defined
%

Now run a script, with the identical file in place:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# probe.tcl
puts "  script running"
puts "  SITE_SETTING exists? [info exists ::SITE_SETTING]"
puts "  site_helper defined? '[info procs site_helper]'"

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  script running
  SITE_SETTING exists? 0
  site_helper defined? ''

The interpreter will tell you which file it would use:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  tcl_rcFileName     : ~/.tclshrc

2. What a tool sources

A real tool typically sources several files, in a defined order, from several places. The categories are consistent even though names are not:

Category	Typically contains
Tool defaults	the vendor's own initialisation
Site / installation	settings the CAD group applies to everyone
Project	library paths, technology, corner definitions for this chip
User	personal aliases, procedures and preferences

Later files normally override earlier ones, so the user file wins — which is convenient and is exactly why one person's session can differ from another's.

I am not going to name specific filenames here, because they differ by vendor and version and I cannot verify them for your tool. Find the real answer yourself:

Read the tool's installation or getting-started guide for "startup", "init" or "setup".
Check the environment for variables pointing at setup files or library paths.
At the prompt, ask: info commands *setup*, info commands *init*, and look for a variable the tool sets to its own rc file name, the way Tcl sets tcl_rcFileName.
Many tools print the files they sourced in the session log — Chapter 17.3.

Doing that once per tool is worth an afternoon.

3. Why order matters

Three ordered setup files, each adjusting a setting:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# setup/00-site.tcl
set ::LIMIT 100.0
set ::MODE  "site-default"

# setup/10-project.tcl
set ::LIMIT 50.0

# setup/20-user.tcl
set ::MODE "my-override"

Sourced in order:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  sourced: 00-site.tcl   (LIMIT=100.0 MODE=site-default)
  sourced: 10-project.tcl (LIMIT=50.0 MODE=site-default)
  sourced: 20-user.tcl    (LIMIT=50.0 MODE=my-override)
  final: LIMIT=50.0 MODE=my-override

The project file tightened the limit; the user file changed the mode; each later file overrode what it cared about and left the rest alone. That layering is the point of having several files, and it is the same precedence idea as Chapter 15.5 §5's default → environment → option.

4. The silent divergence

Now remove one file — as happens when a colleague has not checked out the project setup, or runs from a different directory, or joined before it existed:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  sourced: 00-site.tcl   (LIMIT=100.0 MODE=site-default)
  sourced: 20-user.tcl    (LIMIT=100.0 MODE=my-override)
  final: LIMIT=100.0 MODE=my-override

5. Making the difference visible

The fix is cheap: record what was loaded, and print the settings that matter.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

set ::SETUP_LOADED {}
set here [file dirname [file normalize [info script]]]
foreach f [lsort [glob -nocomplain [file join $here setup *.tcl]]] {
    source $f
    lappend ::SETUP_LOADED [file tail $f]
}

proc show_setup {} {
    puts "  setup files loaded : $::SETUP_LOADED"
    puts "  effective LIMIT    : $::LIMIT"
    puts "  effective MODE     : $::MODE"
    puts "  tcl_interactive    : $::tcl_interactive"
}

With everything present:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  setup files loaded : 00-site.tcl 10-project.tcl 20-user.tcl
  effective LIMIT    : 50.0
  effective MODE     : my-override
  tcl_interactive    : 0

With one missing:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  setup files loaded : 00-site.tcl 20-user.tcl
  effective LIMIT    : 100.0
  effective MODE     : my-override
  tcl_interactive    : 0

The same divergence, now visible in the first four lines of every run. Two engineers comparing logs find it in seconds instead of hours.

6. Making a script independent of the environment

The deeper fix is to stop depending on startup files at all. A flow script that produces the same result regardless of who runs it has four properties:

It sources what it needs explicitly. If the script requires a library of procedures, it sources that library itself — with the $here idiom from Chapter 15.1 §6 — rather than hoping a startup file did.

It sets its own defaults. Every setting it depends on is initialised in the script, then optionally overridden by the environment and by options, as in Chapter 15.5 §6. Nothing is assumed to arrive pre-set.

It checks its preconditions. The preflight from Chapter 14.10 §8 — the commands it needs, the variables it needs, the files it needs — so a missing setup produces a clear error in the first second rather than a wrong number at the end.

It records what it found. §5.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# Explicit: does not depend on any startup file having run.
set here [file dirname [file normalize [info script]]]
source [file join $here .. lib flow_utils.tcl]

set LIMIT 100.0
if {[info exists ::env(FLOW_LIMIT)]} { set LIMIT $::env(FLOW_LIMIT) }

require_commands read_design get_cells report_area

7. The diagnostic routine

When a script works for you and fails for someone else, in order:

Compare the setup files actually loaded. §5 gives you this for free if you added it; otherwise print it now.
Compare the effective settings, not the files — a file can be present and overridden.
Check interactive versus batch. If yours works at the prompt and theirs fails in batch, suspect a startup file that only runs interactively — §1.
Check the working directory. Project setup is often found relative to it, and so are relative source paths — Chapter 15.1 §5.
Compare the environment, which is where many tools find library and setup paths — Chapter 15.5.
Compare tool versions. info patchlevel plus whatever the tool reports about itself.

Five of those six are answered by printing a few lines at the start of every run.

8. Exercises

Exercise 1. Is ~/.tclshrc sourced when you run tclsh script.tcl?

Exercise 2. Why is "works when I type it, fails when I run it" a sharper description than "works for me, fails for you"?

Exercise 3. Three setup files set the same variable. Which value wins, and why is that useful?

Exercise 4. A colleague's run gives a different number with no error. What should you compare first?

Exercise 5. What four lines would have made that difference obvious immediately?

Exercise 6. Name two properties of a script that does not depend on startup files.

Exercise 7. Your script uses a procedure defined in your personal setup file. What happens when a colleague runs it, and how would you find out before they do?

Answers.

1. No. It is sourced in interactive sessions only — verified both ways. Anything it defines is absent from every batch run.

2. Because it is the same person on the same machine with the same commands. The difference is the mode, not the environment, which makes it much easier to miss — the interactive session hides a dependency the script does not satisfy.

3. The last one sourced. It is useful because it lets site, project and user settings layer — each level overriding only what it cares about.

4. Which setup files were actually loaded, and the effective values of the settings that matter — not whether the files exist, since a present file can be overridden.

5. Printing the loaded setup files and the effective settings at the start of the run — setup files loaded, the key values, and the mode.

6. Any two of: it sources what it needs explicitly; it sets its own defaults; it checks preconditions with a preflight; and it records what it loaded.

7. It fails with invalid command name, or worse, silently takes a different path. Find it first by running the script on a clean account, or in an environment with no personal setup sourced.

Remember.

Startup files run before your first line, and later ones normally override earlier ones.
~/.tclshrc runs interactively only — never in batch. Tool startup files often have the same split.
So "works when I type it, fails when I run it" is a startup-file symptom, not just a console/batch one.
A missing setup file usually produces no error — just a different, confident answer.
Record what was loaded and print the effective settings at the top of every run. Four lines, and it turns hours into seconds.
Find your tool's real startup files once, from its documentation, its environment, its session log, or info commands *init*.
A reproducible script sources what it needs, sets its own defaults, preflights, and logs what it found.
Personal customisations are a hidden dependency the moment a shared script relies on one. Test on a clean account.
When two runs disagree, compare effective settings — not whether the files exist.

Where this fits

Part of the Tcl curriculum.