tm(n) Tcl Built-In Commands tm(n) ______________________________________________________________________________
NAME
tm - Facilities for locating and loading of Tcl Modules
SYNOPSIS
::tcl::tm::path add ?path...?
::tcl::tm::path remove ?path...?
::tcl::tm::path list
::tcl::tm::roots paths
______________________________________________________________________________
DESCRIPTION
This document describes the facilities for locating and loading Tcl
Modules (see MODULE DEFINITION 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 list.
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 be taken.
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 paths
Similar to path add, and layered on top of it. This command
takes a single argument containing 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 default paths.
The command has been exposed to allow a build system to define
additional root paths beyond those described by this document.
MODULE DEFINITION
A Tcl Module is a Tcl Package contained in a single file, and no other
files required by it. This file has to be sourceable. In other words, a
Tcl Module is always imported via:
source module_file
The load command is not directly used. This restriction is not an
actual limitation, as some may believe. Ever since 8.4 the Tcl source
command 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:
([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm
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
FINDING MODULES
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 cool::ice or ice, the
latter potentially obscuring a package named ice, unqualified.
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 "/".
Example:
The requested package is encoding::base64. The generated partial
path is "encoding/base64".
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 MODULE DEFINITION. For the remaining files provide
scripts are 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 is ignored.
Note that packages in module form have no control over the index and
provide scripts entered into the package database for them. For a
module file MF the index script is always:
package ifneeded PNAME PVERSION [list source MF]
and the provide script embedded in the above is:
source MF
Both package name PNAME and package version PVERSION are extracted from
the filename MF according to the definition below:
MF = /module_path/PNAME'-PVERSION.tm
Where PNAME' is the partial path of the module as defined in section
FINDING MODULES, and translated into PNAME by changing all directory
separators to "::", and module_path is the path (from the list of paths
to search) that we found the module file under.
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 is deployed in the form of a Tcl Module, packages like foo,
fOo, etc. are not allowed anymore.
DEFAULT PATHS
The default list of paths on the module path is computed by a tclsh as
follows, where X is the major version of the Tcl interpreter and y 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 variable.
SYSTEM SPECIFIC PATHS
file normalize [info library]/../tclX/X.y
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:
[info library]/../tcl8/8.4
[info library]/../tcl8/8.3
[info library]/../tcl8/8.2
[info library]/../tcl8/8.1
[info library]/../tcl8/8.0
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 EXEC/tclX/X.y
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 = EXEC_PREFIX the two sets are identical.
SITE SPECIFIC PATHS
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).
USER SPECIFIC PATHS
$::env(TCLX_y_TM_PATH)
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 as well.
$::env(TCLX.y_TM_PATH)
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. TIP 189.
These paths are seen and therefore shared by all Tcl shells in the
$::env(PATH) of the user.
Note that X and y follow the general rules set out above. In other
words, Tcl 8.4, for example, will look at these 10 environment
variables:
$::env(TCL8.4_TM_PATH) $::env(TCL8_4_TM_PATH)
$::env(TCL8.3_TM_PATH) $::env(TCL8_3_TM_PATH)
$::env(TCL8.2_TM_PATH) $::env(TCL8_2_TM_PATH)
$::env(TCL8.1_TM_PATH) $::env(TCL8_1_TM_PATH)
$::env(TCL8.0_TM_PATH) $::env(TCL8_0_TM_PATH)
SEE ALSO
package(n), Tcl Improvement Proposal #189 "Tcl Modules" (online at
https://tip.tcl-lang.org/189.html), Tcl Improvement Proposal #190
"Implementation Choices for Tcl Modules" (online at
https://tip.tcl-lang.org/190.html)
KEYWORDS
modules, package
Tcl 8.5 tm(n)
tcl 8.6.15 - Generated Wed Dec 4 11:00:02 CST 2024