TclIndex

[Explain pkgIndex.tcl (another of the magic names, file variety), package, ...]

[Mention pertinence to "How to change a running system"?]

Be careful not to be confused by the title. Files named tclIndex are special to the Tcl auto-loader, powered by the unknown command.

Files named pkgIndex.tcl are special to tclPkgUnknown, the command registered by default with [package unknown].

The two mechanisms are different, though they (unfortunately) share the global variable $::auto_path.

Auto Loading

If you're building a library of tcl scripts, you should consider using utilizing one of Tcl's auto-loading mechanisms.

If you put a bunch of library scripts in a directory (or set of relative directories), you can use the auto_mkindex command (documented on Tcl's library manual page) to generate a special index file named tclIndex. This index file contains references to all the procedures defined in all the files.

You can then modify your application's auto_path variable to include this new library directory. The auto-loading mechanism will scan the index, and when you call one of the indexed procedures, it will know where to find it. No source command is required.

JMN Why would one choose to use this mechanism instead of 'package require'? I've seen some packages such as 'interface' & 'vfs' that seem to provide both.

Is for example, the provision of the tclIndex file in the tclVfs distribution there merely as a convenience for those who may want to set up the package for use without explicit 'package require' statements?

Are there any relevant performance issues to consider with regards to the two mechanisms?

Any comments on the desirability or 'style' of doing things the tclIndex way.. or is it just up to personal taste?

LV Two comments from the peanut gallery - the tclIndex was the first loading mechanism provided, and secondly, if I understand this correctly, it works by hooking into the unknown proc. If you issue a proc, and tcl doesn't know about it, tcl then looks at the various tclIndex in the autopath to determine the first occurence of the proc name in one of the files. That occurence will have, associated with it, a source command to execute. The program doesn't issue a package require.

RS 2007-09-25: Here's a little script to examine two or more tclIndex files for command name duplications. These can be a problem if the order in which the files are sourced is not well-known, as the last setting always wins. The script reports such duplications, allowing to fix them by removing all but one instance of the conflicting names.

 #!/usr/bin/env tclsh
 set usage {$Id$
    usage: compare_tclIndex.tcl tclIndex1 tclIndex2 ...
    reports functions that are defined in more than one of the specified index files
    to stdout
 }
 if {[llength $argv] < 2} {puts stderr $usage; exit 1}
 trace add variable auto_index write tracer

 proc tracer {_arr key op} {
    upvar 1 $_arr arr
    global backup
    if [info exists backup($key)] {
        puts "$key\t$arr($key) redefines $backup($key)"
    } else {
        set backup($key) $arr($key)
    }
 }
 foreach file $argv {
    set dir [file dirname $file]
    source $file
 }

To prevent procs from ending up in tclIndex (maybe causing confusion by duplicates), a simple way is to write early in the file

 interp alias {} _proc {} proc

and then use _proc to define functions. Works like proc (obviously), but suppresses indexing. (RS)