An index file corresponding to the mumble.tlib file is called mumble.tndx. TclX will automatically re-create this index file if it is missing or out of date (provided of course that the user running TclX has write access to the library directory).
The global variable auto_path (analogous to the envar PATH) contains a list of directories to be searched, in order, for tlib files. On the first unknown command trap during an execution of TclX code, the indices for libraries on this path are loaded into memory. The first package that contains the missing command will be loaded in its entirety (all commands which are part of that package will be loaded). In other words, say you have a tlib file foo.tlib:
#@package: MyPackageName myproc1 myproc2 myproc3 myproc4 \
myproc5 myproc6
myproc1 {foo faa} {
...
}
myproc2 {fee fie} {
...
}
and so forth. This tlib file is in a directory which is found in the
auto_path variable. Now, in your TclX code, you have a call to
myproc1:
if {$err} {
myproc1 azuki garbanzo
}
myproc1 has not been previously defined in your source, so you get
an unknown command trap. You search your auto_path and load in the
indices for all tlibs on that path. Then, searching the loaded
indices, you find myproc1 in the MyPackageName
package. You load in
all the procs in that package. Now you can resolve the missing
command name.
You can also explicitly load a particular tlib file at the start of your source code, rather than relying on auto-path. Whichever method you use, beware of duplicate procedure names in your tlib files. The first package containing the procedure with the name of the missing command is the one that will get loaded.
The command auto_packages will return a list of all the defined packages (established by the automatic loading of tndx files along the auto_path, at startup). The command auto_commands will tell the names of all known (found in loaded indices) commands that can be auto-loaded. With the -loaders option it will specify as well the command that will be executed to load the command.:
tcl> auto_packages
TclX-convertlib TclX-buildhelp TclX-ucblib TclX-Compatibility ...
tcl> tcl>auto_commands -loaders
{write_file {auto_load_pkg {TclX-stringfile_functions}}}
{sin {auto_load_pkg {TclX-fmath}}}
{assign_fields {auto_load_pkg {TclX-Compatibility}}}
{log10 {auto_load_pkg {TclX-fmath}}} ...
(I have formatted this for legibility: in each case the output is actually
just one long list without newlines).The command auto_load commandName will attempt to load commandName from a tlib file somewhere, by loading the entire package in which commandName is found. The command auto_load_file fileName will attempt to source the file fileName, but will search for it along auto_path rather than in the current directory.
The generally useful command searchPath dirPath fileName was developed to support TclX libraries and packages: dirPath is a list of directory specifications, which will be searched for fileName. The return value is the full path name of the file.
The command buildpackageindex listOfTlibs allows you to force a rebuild of the index files for every tlib file in the list. Note: the filenames must include the .tlib suffix.) Of course, you have to have write access to the directories where the tlib files reside, because new tndx files will be created. The command loadlibindex tlibFile forces a load of the entire contents of tlibFile. This command allows you to load tlib files which are not found on auto_path (or, looked at in a slightly different light, relieves you of the need to maintain a complex auto_path).
You can, in fact, use loadlibindex to override a previous load of the index for a named package, writing an experimental version over a production version for example; however, if any procedure has actually been invoked from the previously loaded version of the package, the override will fail and the procedure definitions from the earlier load will persist.
Lastly, convert_lib tclIndexFile tlibFile [ignore] will convert an existing old-style tclIndex file and its associated source files into a tclX package library. In this case you can leave the .tlib extension off tlibFile and it will be appended for you. The optional list ignoreList specifies tcl source files to be ignored when the tlib file is constructed. Note that the file names in the ignoreList should be only base filenames, without paths.
The tclX method of maintaining code libraries is tidy and flexible. It is functionally analogous to object libraries, in that a single file is used to store an archive of functions and subroutines, which can be loaded at will into applications. I find tlib files extremely useful for organizing procedures into general-purpose and specific functions, for example; the general-purpose library ucosyb.tlib is loaded (via loadlibindex) in all my sybase/tcl applications, but each app has also its own private tlib full of functions and subroutines useful only to itself.
I usually maintain individual Tcl procedure modules in an RCS directory, with a Makefile which constructs a tlib out of them. This is comfortably analogous to the normal C development style, gives me individual revision control over each procedure, and yet makes my code easy to package and export (usually each application consists only of one "main" and one or two tlib files).