To access the procedures in the Tcl library, an application should source the file init.tcl in the library, for example with the Tcl command
source [file join [info library] init.tcl]
If the library procedure Tcl_Init is invoked from an application's Tcl_AppInit procedure, this happens automatically. The code in init.tcl will define the unknown procedure and arrange for the other procedures to be loaded on-demand using the auto-load mechanism defined below.
On platforms other than Windows, if cmd contains any path separators, auto_execok checks for the existence of an executable file with that path. If present, it is returned as the first element of the returned list. Note that this may be a relative path. If cmd does not contain any path separators, all directories in the PATH environment variable are searched for an executable file of that name. If found, a list containing a single element holding the full path to the file is returned.
The rest of this description applies to Windows platforms.
If cmd contains path separators, the command checks for the existence of a file of that name. If found, the file associations in the Windows registry is looked up to retrieve the template for the file's extension. On success, the template is processed to replace environment variables, placeholders for the file path, converted to list form and returned. Otherwise, an empty list is returned.
If cmd does not contain path separators, it is first matched against the built-in commands in the cmd.exe command shell. Built-ins that are intended only for batch file use are excluded. On a match, the returned list is the list of arguments to be passed to exec to run the built-in using cmd.exe.
Next, auto_execok searches directories in the following order: the directory of the process executable, the current working directory (subject to conditions described below), the Windows system32 directory, the Windows directory and the directories in the PATH environment variable. Within each directory, the command will look for a file matching the passed name, and if not found, for a file matching the passed name appended with extensions listed in the PATHEXT environment variable. The extension of the matched file is looked up in the file associations in the registry and the corresponding template is returned after processing as described earlier.
Inclusion of the current working directory in the list of examined directories depends on Windows system settings retrieved with the NeedCurrentDirectoryForExePathW Win32 API. Refer to its documentation for details. Note that if the current directory, ., is explicitly included in PATH, it is not affected by this setting.
Finally, if all above fails, cmd is looked up in the App Paths key in the Windows registry after appending .exe if not already present. If listed there as a registered application, its path is returned as the first (and only) list element.
To run the DIR shell builtin on Windows, you would do:
exec {*}[auto_execok dir]
To open a .txt file on Windows with the associated program, you would do:
exec {*}[auto_execok path/to/foo.txt]
Note in the above that since .txt is not generally included in PATHEXT, the passed name is not searched for even if it does not include any path separators.
To discover if there is a frobnicate that can be run by exec, you would do:
set mayFrob [expr {[llength [auto_execok frobnicate]] > 0}]
It is not normally necessary to call this command directly.
It is not normally necessary to call this command directly; the default unknown handler will do so.
auto_mkindex foo *.tcl
will read all the .tcl files in subdirectory foo and generate a new index file foo/tclIndex.
Auto_mkindex parses the Tcl scripts by sourcing them into a child interpreter and monitoring the proc and namespace commands that are executed. Extensions can use the (undocumented) auto_mkindex_parser package to register other commands that can contribute to the auto_load index. You will have to read through auto.tcl to see how this works.
Auto_mkindex_old (which has the same syntax as auto_mkindex) parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word “proc” as its first characters then it is assumed to be a procedure definition and the next word of the line is taken as the procedure's name. Procedure definitions that do not appear in this way (e.g. they have spaces before the proc) will not be indexed. If your script contains “dangerous” code, such as global initialization code or procedure names with special characters like $, *, [ or ], you are safer using auto_mkindex_old.
Auto_qualify is used by the auto-loading facilities in Tcl, both for producing auto-loading indexes such as pkgIndex.tcl, and for performing the actual auto-loading of functions at runtime.
For example, to print the contents of the tcl_platform array, do:
parray tcl_platform
For example, to print the indices of the starts of each word in a string according to platform rules:
set theString "The quick brown fox"
for {set idx 0} {$idx >= 0} {
set idx [tcl_startOfNextWord $theString $idx]} {
puts "Word start index: $idx"
}
Not normally usefully accessed directly by user code.
Not normally usefully accessed directly by user code.
Use of this environment variable is not recommended outside of testing. Tcl installations should already know where to find their own script files, as the value is baked in during the build or installation.
A key consequence of this variable is that it gives a way to let the user of a script specify the list of places where that script may use package require to read packages from. It is not normally usefully settable within a Tcl script itself except to influence where other interpreters load from (whether made with interp create or launched as their own threads or subprocesses).