[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?