`$auto_path`, one of the [tclvars%|%variables] managed by the interpreter, is a
[list] of directories used by `[package]` to find packages, and also by
`[auto_load]` when searching for commands.



** Description **

If you need, with your application, to add a directory to the auto_path
list, be certain to remember it is a list - so don't make the mistake of treating it as a single value.

Instead use something like

======
set auto_path [linsert $auto_path 0 /home/mystuff/someextension/unix] 
======

or

======
lappend auto_path [file join $env(HOME) someextension unix]
======


Always use an absolute path, not a relative one.

Also make certain that auto_path (and env in the second case) are global
references to the variables, either using [global] or '''$::'''

----

Tcl's init.tcl start up code sets auto_path as a global within an interpreter
instance.  As the distribution init.tcl for 8.3 says right at the top,

===
# The values on the path come from several locations:
#
# The environment variable TCLLIBPATH
#
# tcl_library, which is the directory containing this init.tcl script.
# tclInitScript.h searches around for the directory containing this
# init.tcl and defines tcl_library to that location before sourcing it.
#
# The parent directory of tcl_library. Adding the parent
# means that packages in peer directories will be found automatically.
#
# Also add the directory where the executable is located, plus ../lib
# relative to that path.
#
# tcl_pkgPath, which is set by the platform-specific initialization routines
#       On UNIX it is compiled in
#       On Windows, it is not used
#       On Macintosh it is "Tool Command Language" in the Extensions folder
===


Two points to emphasize from the above:

   * Notice the rather baroque mixture of platform-dependence, generation-time, and run-time assignments.
   * As is customary in idiomatic Tcl, "the directory where the executable is located" refers to tclsh (and so on), rather than, for example, my_script.tcl.  This directory is omitted in Tcl 8.4 and 8.5.

----

Question: is there a Wiki page that discusses how the whole Tcl start up,
locate extension, load extension thing works?  One of the toughest problems
I encounter with Tcl is figuring out how to fix problems when an extension
I think should load, doesn't load.

For instance, [Tix] is a Tk based extension.  When one installs it, it
places the .so in $[exec-prefix]/lib and its scripting in
$[exec-prefix]/lib/tix8.2/ (or whatever version is being installed).

When this is a normal file system, and one does the

======
package require Tk
package require Tix
======

the extension is found, loaded, and things work.  When the same directory
structure is used within a [starkit], an error about not finding the Tix script
code is generated.

Understanding the process better - and perhaps some debugging tools - would
make fixing things like this easier.

<<categories>> Internals