1tm(n)                        Tcl Built-In Commands                       tm(n)


8       tm - Facilities for locating and loading of Tcl Modules


11       ::tcl::tm::path add path...
12       ::tcl::tm::path remove path...
13       ::tcl::tm::path list
14       ::tcl::tm::roots path...


18       This  document  describes  the  facilities for locating and loading Tcl
19       Modules. The following commands are supported:
21       ::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.
26              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.
33              If  a path is already present as is, no error will be raised and
34              no action will be taken.
36              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.
41       ::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.
45       ::tcl::tm::path list
46              Returns a list containing all registered module  paths,  in  the
47              order that they are searched for modules.
49       ::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
52tclX/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.
57              This command is used internally by the system to set up the sys‐
58              tem-specific default paths.
60              The  command  has been exposed to allow a build system to define
61              additional root paths beyond those described by this document.


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
69       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.
76       The name of a module file has to match the regular expression:
77              ([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\.tm
79       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


86       The directory tree for storing Tcl modules is separate from other parts
87       of the filesystem and independent of auto_path.
89       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:
94              For any two directories, neither is an ancestor directory of the
95              other.
97       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.
102       Before the search is started, the name  of  the  requested  package  is
103       translated into a partial path, using the following algorithm:
105              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 “/”.
109       Example:
111              The requested package is encoding::base64. The generated partial
112              path is “encoding/base64”.
114       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.
121       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.
125       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
132       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
136       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.
141       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.
147       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.


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.
158       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.
164       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.
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.
174              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
181              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.
185       file normalize EXEC/tclX/X.y
186              Where  EXEC  is file normalize [info nameofexecutable]/../lib or
187              file normalize [::tcl::pkgconfig get libdir,runtime]
189              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.
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).
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.
205       $::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.
212       These paths are seen and therefore shared by  all  Tcl  shells  in  the
213       $::env(PATH) of the user.
215       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)


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)


230       modules, package
234Tcl                                   8.5                                tm(n)