auto_path is one of the [magic names] that Tcl knows.

It is a global variable containing a [list] of directories that Tcl uses when attempting either to resolve packages with the [package] command, or to resolve commands using [auto_load].  The [package] and [auto_load] commands use auto_path in different ways.

auto_load searches the auto_path directories looking for files named tclIndex.  These are
"Tcl autoload index files", and are formatted in two versions; version 2.0 contains commands
  set auto_index(::namespace::function_name) $cmd
where $cmd typically sources a file that defines the command ::namespace::function_name

In contrast, init.tcl states that package resolution "scans
the auto_path directories ''and their immediate children'' looking for
pkgIndex.tcl files and sources any such files that are found to setup
the package database. As it searches, ''it will recognize changes
to the auto_path and scan any new directories''."

The auto_path is modified in this way by (for example) the pkgIndex.tcl files for [tcllib] and [tklib] - each adds its own directory to auto_path so that its child directories will be scanned.

----
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
that [LV] made and treat 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.

----

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