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