1tm(n)                        Tcl Built-In Commands                       tm(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tm - Facilities for locating and loading of Tcl Modules
9

SYNOPSIS

11       ::tcl::tm::path add ?path...?
12       ::tcl::tm::path remove ?path...?
13       ::tcl::tm::path list
14       ::tcl::tm::roots ?path...?
15______________________________________________________________________________
16

DESCRIPTION

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
22       ::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
27              The  command  enforces  the  restriction  that no path may be an
28              ancestor directory of any other path on the list. If any of  the
29              new  paths  violates  this  restriction an error will be raised,
30              before 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
34              If a path is already present as is, no error will be raised  and
35              no action will be taken.
36
37              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
42       ::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
46       ::tcl::tm::path list
47              Returns  a  list  containing all registered module paths, in the
48              order that they are searched for modules.
49
50       ::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
53tclX/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
58              This command is used internally by the system to set up the sys‐
59              tem-specific default paths.
60
61              The command has been exposed to allow a build system  to  define
62              additional root paths beyond those described by this document.
63

MODULE DEFINITION

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
69              source module_file
70
71       The  load  command  is  not  directly  used. This restriction is not an
72       actual 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
78       The name of a module file has to match the regular expression:
79
80              ([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm
81
82       The first capturing parentheses provides the name of the  package,  the
83       second  clause  its  version.  In addition to matching the pattern, the
84       extracted version number must not raise an error when used in the  com‐
85       mand:
86
87              package vcompare $version 0
88

FINDING MODULES

90       The directory tree for storing Tcl modules is separate from other parts
91       of the filesystem and independent of auto_path.
92
93       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
98              For any two directories, neither is an ancestor directory of the
99              other.
100
101       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
106       Before  the  search  is  started,  the name of the requested package is
107       translated into a partial path, using the following algorithm:
108
109              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
113       Example:
114
115              The requested package is encoding::base64. The generated partial
116              path is “encoding/base64”.
117
118       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
125       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
129       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
133              package ifneeded PNAME PVERSION [list source MF]
134
135       and the provide script embedded in the above is:
136
137              source MF
138
139       Both package name PNAME and package version PVERSION are extracted from
140       the filename MF according to the definition below:
141
142              MF = /module_path/PNAME′-PVERSION.tm
143
144       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
149       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
155       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

DEFAULT PATHS

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
166       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
172       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
176   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
182              For example for Tcl 8.4 the paths searched are:
183
184                     [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
190              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
194       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
198              This  sets  of  paths  is handled equivalently to the set coming
199              before, except that it is anchored in EXEC_PREFIX.  For a  build
200              with PREFIX = EXEC_PREFIX the two sets are identical.
201
202   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
207   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
214       $::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
221       These  paths  are  seen  and  therefore shared by all Tcl shells in the
222       $::env(PATH) of the user.
223
224       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
228              $::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

SEE ALSO

235       package(n), Tcl Improvement Proposal  #189  “Tcl  Modules”  (online  at
236       http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 “Implementa‐
237       tion Choices for Tcl Modules” (online at http://tip.tcl.tk/190.html)
238

KEYWORDS

240       modules, package
241
242
243
244Tcl                                   8.5                                tm(n)
Impressum