Tcl · Module 27

A Variable Contract Between Scripts

A shared setup file is a shared global namespace. A contract is what turns reading one of those variables from an invisible dependency into a declared one.

Foundation18 min readtcledapart-iiinfrastructurevalidationconventions

Part II · Module 27 · Chapter 27.4 · A Variable Contract Between Scripts

Chapter 27.3 §4 ended on a problem: a shared setup file is a shared mutable global namespace, and a script that reads one of its variables creates a dependency that leaves no trace.

A contract is the smallest thing that fixes that.

1. What the default failure looks like

Without a contract, a missing variable is discovered by using it:

can't read "LIB_PATH": no such variable

That message is accurate and nearly useless. It does not say which script needed it, what it was for, whether it was supposed to have a default, or who was meant to set it. And it arrives wherever the variable was first read — typically three steps into a flow, after the tool has loaded a design and a licence has been checked out.

The whole of this chapter is the difference between that and a message produced before any work starts.

2. The contract

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

namespace eval ::flow {
    variable CONTRACT {
        {DESIGN      required {}          {the top-level module name}}
        {FLOW_ROOT   required {}          {absolute path to the flow tree}}
        {STAGE       required {}          {synth | place | route}}
        {OUT_DIR     optional work        {where outputs are written}}
        {LIB_PATH    optional libs        {technology library directory}}
        {VERBOSE     optional 0           {1 for per-step detail}}
        {STOP_ON_ERR optional 1           {0 to continue past a failed step}}
    }
}

Four fields per entry: the name, whether it is required, its default, and what it means.

That last field is what makes this a contract rather than a list. A name alone tells a reader nothing about whether OUT_DIR is absolute or relative, or what STAGE may contain — and the meaning string is what appears in the error message, where it is needed most.

Three properties of the shape are worth naming:

It is data, not code. Adding a variable is one line. The validator does not change, and neither does anything else — the same argument as Chapter 25.3 §4's rules-as-data and Chapter 26.4 §3's prune-rules-as-data.

Required and optional are distinguished explicitly. Without that distinction a validator cannot tell "the caller forgot" from "the caller accepted the default".

The defaults live beside the declaration, not scattered through the code as [expr {[info exists ::X] ? $::X : 0}]. One place to read what happens when a variable is absent.

3. Validating in two passes

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc ::flow::validate_vars {} {
    # PASS 1: find every missing required variable, and change NOTHING.
    set missing {}
    foreach e $::flow::CONTRACT {
        lassign $e name kind default meaning
        if {$kind eq "required" && ![info exists ::$name]} {
            lappend missing [format "    %-12s %s" $name $meaning]
        }
    }
    if {[llength $missing]} {
        error "[llength $missing] required variable(s) not set:\n[join $missing \n]" \
              {} [list FLOW MISSINGVARS [llength $missing]]
    }
    # PASS 2: only now apply the optional defaults.
    set defaulted {}
    foreach e $::flow::CONTRACT {
        lassign $e name kind default meaning
        if {$kind eq "optional" && ![info exists ::$name]} {
            set ::$name $default
            lappend defaulted [format "%s=%s" $name $default]
        }
    }
    return $defaulted
}

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== nothing set: the error names every missing variable ===
catch 1
3 required variable(s) not set:
    DESIGN       the top-level module name
    FLOW_ROOT    absolute path to the flow tree
    STAGE        synth | place | route

All three at once, each with its meaning. A validator that raised on the first missing variable would need three runs to tell you what you forgot, and the registry's phrase — "fails immediately with a clear message" — means one message naming everything.

4. Why two passes

My first version walked the contract once, applying defaults as it went. That meant a validation that failed had already changed four variables.

The single-pass loop set OUT_DIR, LIB_PATH, VERBOSE and STOP_ON_ERR on its way to discovering that DESIGN, FLOW_ROOT and STAGE were missing — and then raised. The caller catches the error, decides to try something else, and is now working in a session where half the contract has been silently populated.

That is precisely Chapter 26.5 §3's hazard: an operation that fails after partially applying its effects, leaving state nobody chose. There the cure was to reset before applying; here it is to check before changing.

The two-pass version is verifiable:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== and NOTHING was changed by the failed validation ===
    DESIGN       <unset>
    FLOW_ROOT    <unset>
    STAGE        <unset>
    OUT_DIR      <unset>
    LIB_PATH     <unset>
    VERBOSE      <unset>
    STOP_ON_ERR  <unset>

All seven still unset after a failed validation. The general rule is worth stating plainly: a function that validates and a function that mutates should not be the same pass, even when they are the same procedure.

Two smaller defects in the same file, both found by running it rather than reading it:

The error listed DESIGN {the top-level module name} with braces. The line was a Tcl list, and lappend missing [list $name $meaning] then renders the two-word meaning braced. Building each line with format instead produces prose.

[join $missing \n ] does not indent. The trailing spaces before the ] are argument separators, so the join string is just \n — the indent was silently dropped. Building the indent into each line with format " %-12s %s" is what actually works. Chapter 14.8 is the general case: whitespace inside a command is structure, not content.

5. Where validation goes

The ordering follows from Chapter 27.3 §6:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

source [file join $FLOW_ROOT lib setup.tcl]     ;# defaults
if {[file exists $CFG]} { source $CFG }         ;# overrides
::flow::validate_vars                            ;# validate LAST

Validation runs after the override file, because validating first checks state that is about to be replaced. A run that would have been fine gets rejected, and — worse — a run that an override made invalid gets accepted.

And it runs before any tool work. Chapter 27.1 §7's exit statuses depend on that: a missing variable is exit 2, a flow failure is exit 1, and the two are only distinguishable if the variable check happens before the flow starts.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

if {[catch {::flow::validate_vars} e]} {
    puts stderr "run_flow.tcl: $e"
    exit 2
}

Note the message is prefixed with the script's own name. An error that reaches a job scheduler's log alongside fifty others needs to say which script produced it — and $argv0 or a literal is both fine; what matters is that it is there.

6. A contract checks presence, not sense

Being honest about what this does and does not buy, because "validated" is a word people over-trust.

Every one of these passes validation:

Set to	Why it passes	What happens later
`DESIGN` = `""`	the variable exists	a path like `work//synth`, or a tool error about an empty name
`STAGE` = `synht`	the variable exists	a stage directory nobody looks in, and no error
`OUT_DIR` = `/root/x`	the variable exists	`ensure_dir` fails on permissions, three steps in
`VERBOSE` = `yes`	the variable exists	`if {$VERBOSE}` raises — `yes` is not a Tcl boolean in `expr`

So presence is the cheapest check and not the only one. The contract extends naturally:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

{STAGE  required {} {synth | place | route} {enum synth place route}}
{VERBOSE optional 0 {1 for per-step detail} {boolean}}
{OUT_DIR optional work {where outputs are written} {writable-dir}}

...with a validator that dispatches on the fifth field. Worth doing for the handful of variables where a wrong value is expensive, and not worth doing for all of them — a validation layer nobody maintains is Chapter 25.3 §5's rule that never fires.

The one value check that always earns its place is the empty string.

DESIGN set to "" is the single most common way a contract is satisfied by nothing: it happens whenever a variable is assigned from an unset environment variable, a command substitution that returned nothing, or a shell wrapper with a typo'd argument.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

if {$kind eq "required" && [string trim [set ::$name]] eq ""} {
    lappend missing [format "    %-12s %s (set, but empty)" $name $meaning]
}

And note string trim: a variable set to a single space is not empty by eq "" and is empty for every practical purpose — the same reason Chapter 23.6's ECO wrapper trims its reason before checking it, and the same reason string is needs -strict (Chapter 14.11).

7. Exercises

Exercise 1. What is wrong with can't read "LIB_PATH": no such variable as a failure?

Exercise 2. Name the four fields of a contract entry and say what the last one is for.

Exercise 3. Why must required and optional be distinguished explicitly?

Exercise 4. Why does the validator report all missing variables rather than the first?

Exercise 5. What did the single-pass validator do wrong, and what is the general rule?

Exercise 6. Why did the error message render a meaning in braces?

Exercise 7. Why does [join $missing \n ] not indent?

Exercise 8. Why must validation run after the override file?

Exercise 9. Give two values that pass a presence check and break later.

Exercise 10. Why is the empty-string check the one value check always worth having, and why string trim?

Answers.

1. It does not say which script needed it, what it was for, whether it should have had a default, or who was meant to set it — and it arrives after the tool has loaded a design and taken a licence.

2. Name, required-or-optional, default, and meaning. The meaning is what appears in the error message, where a reader most needs to know what the variable is for.

3. Because without it a validator cannot distinguish "the caller forgot" from "the caller accepted the default".

4. Because otherwise you need one run per missing variable to learn what you forgot. "Fails immediately with a clear message" means one message naming everything.

5. It applied optional defaults while discovering that required ones were missing, so a failed validation left four variables silently set. The rule: validating and mutating should not be the same pass.

6. Because the line was built with list, which braces a multi-word element. format produces prose.

7. Because the spaces before the ] are argument separators, so the join string is just \n. The indent has to be built into each line.

8. Because the override file changes settings afterwards, so validating first checks state about to be replaced — rejecting runs that would have been fine and accepting ones the override made invalid.

9. Any two of: DESIGN set to the empty string; STAGE misspelled, which silently produces a directory nobody looks in; OUT_DIR pointing somewhere unwritable; VERBOSE set to yes, which is not a Tcl boolean in expr.

10. Because an empty value is how a contract gets satisfied by nothing — an unset environment variable, an empty command substitution, a typo'd wrapper argument. string trim because a single space is not eq "" and is empty for every practical purpose.

Remember.

no such variable is accurate and useless — and it arrives after a licence has been taken.
A contract entry is name, required-or-optional, default, meaning. The meaning is what the error message needs.
Keep it as data, so adding a variable is one line and the validator never changes.
Report every missing variable at once, each with its meaning.
Validate in two passes: check before changing. A single pass applies defaults while discovering a failure, leaving partial state.
Validating and mutating should not be the same pass.
list braces a multi-word element; use format. And whitespace before a ] is a separator, not an indent.
Defaults, then overrides, then validation — and validation before any tool work, so a setup failure is exit 2 rather than exit 1.
Prefix the message with the script's name, for the log it will land in.
A contract checks presence, not sense. Add value checks only where a wrong value is expensive.
Always check for the empty string, with string trim. That is how a contract gets satisfied by nothing.

Where this fits

Part of the Tcl curriculum.