Practical Programming in Tcl & Tk, Third Edition By Brent B. Welch
Table of Contents
Chapter 12. Script Libraries and Packages
The basic structure of package loading works like this:
An application does a package require command. If the package is already loaded, the command just returns the version number of the already loaded package. If is not loaded, the following steps occur.
The package facility checks to see if it knows about the package. If it does, then it runs the Tcl scripts registered with the package ifneeded command. These commands either load the package or set it up to be loaded automatically when its commands are first used.
If the package is unknown, the tclPkgUnknown procedure is called to find it. Actually, you can specify what procedure to call to do the lookup with the package unknown command, but the standard one is tclPkgUnknown.
The tclPkgUnknown procedure looks through the auto_path directories and their subdirectories for pkgIndex.tcl files. It sources those to build an internal database of packages and version information. The pkgIndex.tcl files contain calls to package ifneeded that specify what to do to define the package. The standard action is to call the tclPkgSetup procedure that sets up the auto_index so that the commands in the package will be automatically loaded. If you use -direct with pkg_mkIndex, the script contains source and load commands instead.
The tclPkgSetup procedure defines the auto_index array to contain the correct source or load commands to define each command in the package. Automatic loading and the auto_index array are described in more detail later.
As you can see, there are several levels of processing involved in finding packages. The system is flexible enough that you can change the way packages are located and how packages are loaded. The default scenario is complicated because it uses the delayed loading of source code that is described in the next section. Using the -direct flag to pkg_mkIndex simplifies the situation somewhat. In any case it all boils down to three key steps:
Use pkg_mkIndex to maintain your index files. Decide at this time whether or not to use direct package loading.
Put the appropriate package require and package provide commands in your code.
Ensure that your library directories, or their parent directories, are listed in the auto_path variable.
