Hopefully someone can write a bit comparing and contrasting the use of this variable and TCLLIBPATH, and the Tcl variable $auto_path, describing to the developer when each should and should not be used, and to the user of Tcl applications just when each are safe or not safe to set.
Another useful thing to document here is what the format for the value should be. Is this a colon seperated series of directories, a space seperated list of directories, or some kind of list of paths to pkgindex.tcl files, or just a single path?
See also magic names.
Usage of TCLLIBPATH versus auto_path
TCL uses auto_path to search the path for libraries on "package require" call. When it startsup, it updates auto_path using TCLLIBPATH and other info. See PkgIndex.tcl for more info.
Example Context
I use a hosting provider with virtual server. Default TCL libraries are in /usr/lib/tclxxx . I want to use libraries in tcllib.sourceforge.net. I can't install them under /usr/lib. I install them under /home/<myid>/tcllib. For testing, I set environment variable TCLLIBPATH before going into tclsh's interactive shell. So "package require xxx" is successful.
In CGI scripts , I need to do "package require ncgi" . I can't control the environment of CGI scripts. So I "lappend autopath <package path>" before doing "package require"