1tm(n) Tcl Built-In Commands tm(n)
2______________________________________________________________________________
6
8 tm - Facilities for locating and loading of Tcl Modules
9
11 ::tcl::tm::path add ?path...?
12 ::tcl::tm::path remove ?path...?
13 ::tcl::tm::path list
14 ::tcl::tm::roots ?path...?
15______________________________________________________________________________
16
18 This document describes the facilities for locating and loading Tcl
19 Modules (see MODULE DEFINITION for the definition of a Tcl Module).
20 The following commands are supported:
21 ::tcl::tm::path add ?path...?
23 The paths are added at the head to the list of module paths, in
24 order of appearance. This means that the last argument ends up
25 as the new head of the list.
26 The command enforces the restriction that no path may be an an‐
28 cestor directory of any other path on the list. If any of the
29 new paths violates this restriction an error will be raised, be‐
30 fore any of the paths have been added. In other words, if only
31 one path argument violates the restriction then none will be
32 added.
33 If a path is already present as is, no error will be raised and
35 no action will be taken.
36 Paths are searched later in the order of their appearance in the
38 list. As they are added to the front of the list they are
39 searched in reverse order of addition. In other words, the paths
40 added last are looked at first.
41 ::tcl::tm::path remove ?path...?
43 Removes the paths from the list of module paths. The command
44 silently ignores all paths which are not on the list.
45 ::tcl::tm::path list
47 Returns a list containing all registered module paths, in the
48 order that they are searched for modules.
49 ::tcl::tm::roots ?path...?
51 Similar to path add, and layered on top of it. This command
52 takes a list of paths, extends each with “tclX/site-tcl”, and
53 “tclX/X.y”, for major version X of the Tcl interpreter and minor
54 version y less than or equal to the minor version of the inter‐
55 preter, and adds the resulting set of paths to the list of paths
56 to search.
57 This command is used internally by the system to set up the sys‐
59 tem-specific default paths.
60 The command has been exposed to allow a build system to define
62 additional root paths beyond those described by this document.
63
65 A Tcl Module is a Tcl Package contained in a single file, and no other
66 files required by it. This file has to be sourceable. In other words, a
67 Tcl Module is always imported via:
68 source module_file
70 The load command is not directly used. This restriction is not an ac‐
72 tual limitation, as some may believe. Ever since 8.4 the Tcl source
73 command reads only until the first ^Z character. This allows us to com‐
74 bine an arbitrary Tcl script with arbitrary binary data into one file,
75 where the script processes the attached data in any it chooses to fully
76 import and activate the package.
77 The name of a module file has to match the regular expression:
79 ([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm
81 The first capturing parentheses provides the name of the package, the
83 second clause its version. In addition to matching the pattern, the ex‐
84 tracted version number must not raise an error when used in the com‐
85 mand:
86 package vcompare $version 0
88
90 The directory tree for storing Tcl modules is separate from other parts
91 of the filesystem and independent of auto_path.
92 Tcl Modules are searched for in all directories listed in the result of
94 the command ::tcl::tm::path list. This is called the Module path. Nei‐
95 ther the auto_path nor the tcl_pkgPath variables are used. All direc‐
96 tories on the module path have to obey one restriction:
97 For any two directories, neither is an ancestor directory of the
99 other.
100 This is required to avoid ambiguities in package naming. If for example
102 the two directories “foo/” and “foo/cool” were on the path a package
103 named cool::ice could be found via the names cool::ice or ice, the lat‐
104 ter potentially obscuring a package named ice, unqualified.
105 Before the search is started, the name of the requested package is
107 translated into a partial path, using the following algorithm:
108 All occurrences of “::” in the package name are replaced by the
110 appropriate directory separator character for the platform we
111 are on. On Unix, for example, this is “/”.
112 Example:
114 The requested package is encoding::base64. The generated partial
116 path is “encoding/base64”.
117 After this translation the package is looked for in all module paths,
119 by combining them one-by-one, first to last with the partial path to
120 form a complete search pattern. Note that the search algorithm rejects
121 all files where the filename does not match the regular expression
122 given in the section MODULE DEFINITION. For the remaining files provide
123 scripts are generated and added to the package ifneeded database.
124 The algorithm falls back to the previous unknown handler when none of
126 the found module files satisfy the request. If the request was satis‐
127 fied the fall-back is ignored.
128 Note that packages in module form have no control over the index and
130 provide scripts entered into the package database for them. For a mod‐
131 ule file MF the index script is always:
132 package ifneeded PNAME PVERSION [list source MF]
134 and the provide script embedded in the above is:
136 source MF
138 Both package name PNAME and package version PVERSION are extracted from
140 the filename MF according to the definition below:
141 MF = /module_path/PNAME′-PVERSION.tm
143 Where PNAME′ is the partial path of the module as defined in section
145 FINDING MODULES, and translated into PNAME by changing all directory
146 separators to “::”, and module_path is the path (from the list of paths
147 to search) that we found the module file under.
148 Note also that we are here creating a connection between package names
150 and paths. Tcl is case-sensitive when it comes to comparing package
151 names, but there are filesystems which are not, like NTFS. Luckily
152 these filesystems do store the case of the name, despite not using the
153 information when comparing.
154 Given the above we allow the names for packages in Tcl modules to have
156 mixed-case, but also require that there are no collisions when compar‐
157 ing names in a case-insensitive manner. In other words, if a package
158 Foo is deployed in the form of a Tcl Module, packages like foo, fOo,
159 etc. are not allowed anymore.
160
162 The default list of paths on the module path is computed by a tclsh as
163 follows, where X is the major version of the Tcl interpreter and y is
164 less than or equal to the minor version of the Tcl interpreter.
165 All the default paths are added to the module path, even those paths
167 which do not exist. Non-existent paths are filtered out during actual
168 searches. This enables a user to create one of the paths searched when
169 needed and all running applications will automatically pick up any mod‐
170 ules placed in them.
171 The paths are added in the order as they are listed below, and for
173 lists of paths defined by an environment variable in the order they are
174 found in the variable.
175 SYSTEM SPECIFIC PATHS
177 file normalize [info library]/../tclX/X.y
178 In other words, the interpreter will look into a directory spec‐
179 ified by its major version and whose minor versions are less
180 than or equal to the minor version of the interpreter.
181 For example for Tcl 8.4 the paths searched are:
183 [info library]/../tcl8/8.4
185 [info library]/../tcl8/8.3
186 [info library]/../tcl8/8.2
187 [info library]/../tcl8/8.1
188 [info library]/../tcl8/8.0
189 This definition assumes that a package defined for Tcl X.y can
191 also be used by all interpreters which have the same major num‐
192 ber X and a minor number greater than y.
193 file normalize EXEC/tclX/X.y
195 Where EXEC is file normalize [info nameofexecutable]/../lib or
196 file normalize [::tcl::pkgconfig get libdir,runtime]
197 This sets of paths is handled equivalently to the set coming be‐
199 fore, except that it is anchored in EXEC_PREFIX. For a build
200 with PREFIX = EXEC_PREFIX the two sets are identical.
201 SITE SPECIFIC PATHS
203 file normalize [info library]/../tclX/site-tcl
204 Note that this is always a single entry because X is always a
205 specific value (the current major version of Tcl).
206 USER SPECIFIC PATHS
208 $::env(TCLX_y_TM_PATH)
209 A list of paths, separated by either : (Unix) or ; (Windows).
210 This is user and site specific as this environment variable can
211 be set not only by the user's profile, but by system configura‐
212 tion scripts as well.
213 $::env(TCLX.y_TM_PATH)
215 Same meaning and content as the previous variable. However the
216 use of dot '.' to separate major and minor version number makes
217 this name less to non-portable and its use is discouraged. Sup‐
218 port of this variable has been kept only for backward compati‐
219 bility with the original specification, i.e. TIP 189.
220 These paths are seen and therefore shared by all Tcl shells in the
222 $::env(PATH) of the user.
223 Note that X and y follow the general rules set out above. In other
225 words, Tcl 8.4, for example, will look at these 10 environment vari‐
226 ables:
227 $::env(TCL8.4_TM_PATH) $::env(TCL8_4_TM_PATH)
229 $::env(TCL8.3_TM_PATH) $::env(TCL8_3_TM_PATH)
230 $::env(TCL8.2_TM_PATH) $::env(TCL8_2_TM_PATH)
231 $::env(TCL8.1_TM_PATH) $::env(TCL8_1_TM_PATH)
232 $::env(TCL8.0_TM_PATH) $::env(TCL8_0_TM_PATH)
233
235 package(n), Tcl Improvement Proposal #189 “Tcl Modules” (online at
236 https://tip.tcl-lang.org/189.html), Tcl Improvement Proposal #190 “Im‐
237 plementation Choices for Tcl Modules” (online at https://tip.tcl-
238 lang.org/190.html)
239
241 modules, package
242Tcl 8.5 tm(n)