tm - Facilities for locating and loading of Tcl Modules
::tcl::tm::path add ?path...?
::tcl::tm::path remove ?path...?
This document describes the facilities for locating and loading Tcl Modules (see
for the definition of a Tcl Module). The following
commands are supported:
- ::tcl::tm::path add ?path...?
- The paths are added at the head to the list of module paths, in order of
appearance. This means that the last argument ends up as the new head of
The command enforces the restriction that no path may be an ancestor directory
of any other path on the list. If any of the new paths violates this
restriction an error will be raised, before any of the paths have been added.
In other words, if only one path argument violates the restriction then none
will be added.
If a path is already present as is, no error will be raised and no action will
Paths are searched later in the order of their appearance in the list. As they
are added to the front of the list they are searched in reverse order of
addition. In other words, the paths added last are looked at first.
- ::tcl::tm::path remove ?path...?
- Removes the paths from the list of module paths. The command silently
ignores all paths which are not on the list.
- ::tcl::tm::path list
- Returns a list containing all registered module paths, in the order that
they are searched for modules.
- ::tcl::tm::roots ?path...?
- Similar to path add, and layered on top of it. This command takes a
list of paths, extends each with “
tclX/site-tcl”, and “
tclX /X.y”, for major
version X of the Tcl interpreter and minor version y less
than or equal to the minor version of the interpreter, and adds the
resulting set of paths to the list of paths to search.
This command is used internally by the system to set up the system-specific
The command has been exposed to allow a build system to define additional root
paths beyond those described by this document.
A Tcl Module is a Tcl Package contained in a single file, and no other files
required by it. This file has to be source
able. In other words, a Tcl
Module is always imported via:
command is not directly used. This restriction is not an actual
limitation, as some may believe. Ever since 8.4 the Tcl source
reads only until the first ^Z character. This allows us to combine an
arbitrary Tcl script with arbitrary binary data into one file, where the
script processes the attached data in any it chooses to fully import and
activate the package.
The name of a module file has to match the regular expression:
The first capturing parentheses provides the name of the package, the second
clause its version. In addition to matching the pattern, the extracted version
number must not raise an error when used in the command:
package vcompare $version 0
The directory tree for storing Tcl modules is separate from other parts of the
filesystem and independent of auto_path
Tcl Modules are searched for in all directories listed in the result of the
command ::tcl::tm::path list
. This is called the Module path
Neither the auto_path
nor the tcl_pkgPath
variables are used.
All directories on the module path have to obey one restriction:
For any two directories, neither is an ancestor directory of the other.
This is required to avoid ambiguities in package naming. If for example the two
directories “ foo/
” and “ foo/cool
were on the path a package named cool::ice
could be found via the names
, the latter potentially obscuring a package
Before the search is started, the name of the requested package is translated
into a partial path, using the following algorithm:
All occurrences of “ ::
” in the package name are replaced
by the appropriate directory separator character for the platform we are on.
On Unix, for example, this is “ /
The requested package is encoding::base64
. The generated partial path is
After this translation the package is looked for in all module paths, by
combining them one-by-one, first to last with the partial path to form a
complete search pattern. Note that the search algorithm rejects all files
where the filename does not match the regular expression given in the section
. For the remaining files provide scripts
generated and added to the package ifneeded database.
The algorithm falls back to the previous unknown handler when none of the found
module files satisfy the request. If the request was satisfied the fall-back
Note that packages in module form have no
control over the index
and provide script
s entered into the package database for them. For a
module file MF
the index script
package ifneeded PNAME PVERSION [list source MF]
and the provide script
embedded in the above is:
Both package name PNAME
and package version PVERSION
from the filename MF
according to the definition below:
MF = /module_path/PNAME′-PVERSION.tm
is the partial path of the module as defined in
section FINDING MODULES
, and translated into PNAME
all directory separators to “ ::
”, and module_path
is the path (from the list of paths to search) that we found the module file
Note also that we are here creating a connection between package names and
paths. Tcl is case-sensitive when it comes to comparing package names, but
there are filesystems which are not, like NTFS. Luckily these filesystems do
store the case of the name, despite not using the information when comparing.
Given the above we allow the names for packages in Tcl modules to have
mixed-case, but also require that there are no collisions when comparing names
in a case-insensitive manner. In other words, if a package Foo
deployed in the form of a Tcl Module, packages like foo
etc. are not allowed anymore.
The default list of paths on the module path is computed by a tclsh
follows, where X
is the major version of the Tcl interpreter and
is less than or equal to the minor version of the Tcl interpreter.
All the default paths are added to the module path, even those paths which do
not exist. Non-existent paths are filtered out during actual searches. This
enables a user to create one of the paths searched when needed and all running
applications will automatically pick up any modules placed in them.
The paths are added in the order as they are listed below, and for lists of
paths defined by an environment variable in the order they are found in the
- file normalize [info
- In other words, the interpreter will look into a directory specified by
its major version and whose minor versions are less than or equal to the
minor version of the interpreter.
For example for Tcl 8.4 the paths searched are:
This definition assumes that a package defined for Tcl X.y
can also be used by all interpreters which have the same major number X
and a minor number greater than y
- file normalize
- Where EXEC is file normalize [info nameofexecutable]/../lib
or file normalize [::tcl::pkgconfig get libdir,runtime]
This sets of paths is handled equivalently to the set coming before, except that
it is anchored in EXEC_PREFIX
. For a build with PREFIX
the two sets are identical.
- file normalize [info library]/../tclX/site-tcl
- Note that this is always a single entry because X is always a
specific value (the current major version of Tcl).
- A list of paths, separated by either : (Unix) or ;
(Windows). This is user and site specific as this environment variable can
be set not only by the user's profile, but by system configuration scripts
- Same meaning and content as the previous variable. However the use of dot
'.' to separate major and minor version number makes this name less to
non-portable and its use is discouraged. Support of this variable has been
kept only for backward compatibility with the original specification, i.e.
These paths are seen and therefore shared by all Tcl shells in the
of the user.
Note that X
follow the general rules set out above. In other
words, Tcl 8.4, for example, will look at these 5 environment variables:
package(n), Tcl Improvement Proposal #189 “ Tcl Modules
(online at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 “
Implementation Choices for Tcl Modules
” (online at