Building SQLite Documentation Fails Due to Missing TCL “Example” Command

Issue Overview: TCL Script Fails with "Invalid Command Name ‘Example’" During Documentation Build

When attempting to build SQLite documentation from source using the docsrc repository, the compilation process fails at the lang_createtrigger.in file with an error indicating an undefined TCL command: "invalid command name ‘Example’". This occurs during execution of documentation generation scripts that process SQL syntax examples embedded in markup files. The failure manifests specifically when TCL interpreter tclsh.docsrc evaluates code blocks containing Example {...} calls designed to format SQL trigger examples.

The build environment requires:

1. A working SQLite source tree
2. TCL 8.6+ development libraries
3. docsrc repository with Fossil version control
4. Properly configured Makefile paths

The error indicates a missing TCL procedure critical to documentation rendering. While the exact failure point (lang_createtrigger.in line 162) appears in CREATE TRIGGER syntax examples, the root cause lies in environment configuration rather than SQL syntax validity.

Possible Causes: Missing TCL Dependencies and Configuration Mismatches

1. TCL Version Mismatch or Incomplete Installation

The documentation build scripts rely on TCL 8.6+ features and custom commands defined in SQLite’s build infrastructure. Older TCL versions (even within 8.6.x) may lack required functionality or exhibit behavioral differences in:

• Namespace handling
• Package loading mechanisms
• Bytecode compilation of procedures

2. Incorrect TCL Library Paths in Makefile

Improper configuration of TCLINC (include paths) and TCLFLAGS (linker flags) may cause:

• Failure to load SQLite-specific TCL extensions
• Partial initialization of documentation generator utilities
• Missing symbol resolutions for custom commands like Example

3. Outdated docsrc/SQLite Code Checkouts

Version skew between components manifests through:

• docsrc expecting newer TCL procedures added in recent SQLite versions
• Missing updates to documentation generator scripts (schema.tcl, wrap.tcl)
• Schema changes in SQLite syntax not reflected in older docsrc checkouts

4. Environment-Specific TCL Configuration Issues

Custom TCL installations or distribution-specific patches may:

• Alter default package search paths
• Modify core command behavior
• Introduce compatibility breaks in namespace resolution

Troubleshooting Steps: Resolving TCL Command Availability and Build Configuration

Step 1: Validate TCL Installation and Version Compatibility

Check TCL Version:

echo 'puts [info tclversion]; exit 0' | tclsh

Confirm output ≥ 8.6. If using tclsh.docsrc wrapper:

./tclsh.docsrc -c 'puts [info tclversion]'

Verify TCL Development Files:

# Fedora/RHEL derivatives
rpm -q tcl-devel

# Debian/Ubuntu derivatives
dpkg -l tcl-dev

Ensure headers and libraries match runtime version.

Test Custom TCL Installation:
If using non-system TCL:

# Verify include files exist
ls -d ${TCLDIR}/include/tcl*.h

# Check library linkage
grep -r 'Example' ${TCLDIR}/lib/*.a ${TCLDIR}/lib/*.so

Step 2: Audit Makefile Configuration for TCL Paths

Critical Makefile Variables:

TCLINC = -I/usr/include/tcl8.6             # Headers
TCLFLAGS = -ltcl8.6 -L/usr/lib64           # Linker flags

Diagnostic Checks:

1. Header Path Validation:

   grep -r 'Example' $(BLD)/*.c $(BLD)/*.h
   

   Locate Example procedure definition in SQLite build artifacts.

2. Library Search Path Verification:

   ldd tclsh.docsrc | grep tcl
   

   Confirm correct TCL library linkage.

3. Static vs Dynamic Linking Issues:
   For static linking (-static in TCLFLAGS), ensure all dependencies (zlib, pthreads) are included.

Reconfiguration Example:

# Custom TCL 8.6.13 build
TCLINC = -I${HOME}/tcl-8.6.13/include
TCLFLAGS = -L${HOME}/tcl-8.6.13/lib -ltcl8.6 -ldl -lm -lpthread -lz

Step 3: Synchronize docsrc and SQLite Source Trees

Update Fossil Checkouts:

# In SQLite source directory
fossil update trunk

# In docsrc directory
fossil update trunk

Validate Commit Dependencies:
Check for version requirements in docsrc’s main.mk:

SQLITE_VERSION = 3.39.0

Compare with SQLite’s sqlite3.h:

#define SQLITE_VERSION        "3.42.0"

Rebuild SQLite Amalgamation:
Fresh rebuild ensures TCL bindings match current source:

cd ${BLD}
make clean
../configure
make tclsqlite3.c sqlite3.c

Step 4: Debug TCL Script Execution

Run Documentation Generator Manually:

./tclsh.docsrc ./wrap.tcl . ../sqlite doc ./pages/lang_createtrigger.in

Add debug statements before error line (162 in lang_createtrigger.in):

puts "Loaded commands: [info commands Example*]"

Trace Command Resolution:

TCLSH_DEBUG=1 ./tclsh.docsrc ./schema.tcl

Look for missing package initializations or namespace imports.

Inspect TCL Environment:
Insert probe in schema.tcl:

proc Example args {
  puts "Example proc called with: $args"
}

If error persists, namespace conflicts are preventing override.

Step 5: Resolve TCL Namespace and Package Issues

Explicit Package Loading:
In documentation scripts (schema.tcl/wrap.tcl), add:

package require sqlite3
namespace import ::sqlite3::*

Diagnose Missing Procedures:
After loading SQLite TCL bindings:

puts "SQLite commands: [info commands sqlite3_*]"

Example Workaround for Missing Command:
Temporarily define Example as pass-through:

if {![llength [info commands Example]]} {
  proc Example {body} {
    hd_puts "<pre class='sql'>"
    hd_puts $body
    hd_puts "</pre>"
  }
}

Step 6: Environment Sanitization and Build Isolation

Clean Build Environment:

make clean
rm -f tclsh.docsrc

Bootstrap Fresh TCL Interpreter:
Recreate tclsh.docsrc wrapper with proper paths:

cat <<EOF > tclsh.docsrc
#!/bin/sh
exec tclsh8.6 "\$@"
EOF
chmod +x tclsh.docsrc

Verify PATH Order:

echo $PATH
which -a tclsh

Ensure system TCL isn’t shadowing custom install.

Step 7: Advanced Diagnostics with TCL Execution Tracing

Enable Command Tracing:

trace add execution Example enterstep leavestep

Log Namespace Changes:

proc unknown args {
  puts "Unknown command: $args"
}

Dump Variable State:
At error point:

puts "Current namespace: [namespace current]"
puts "Loaded packages: [package names]"

Final Resolution Workflow

1. Update Components: Ensure docsrc, SQLite source, and TCL are at latest compatible versions.
2. Verify Paths: Confirm headers and libraries match in Makefile.
3. Isolate Environment: Use clean build directory and fresh checkouts.
4. Manual Script Execution: Run failing TCL script with debug output.
5. Fallback Installation: Build TCL from source if distribution packages are incompatible.

Persistent issues require examining SQLite’s documentation build machinery internals – particularly how Example is injected into the TCL environment during tclsqlite3.c compilation. Cross-referencing with working builds on other systems often reveals subtle configuration discrepancies causing the command resolution failure.