util/src/TclTk/tcl8.6.12/doc/tm.n

   1 '\"
   2 '\" Copyright (c) 2004-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH tm n 8.5 Tcl "Tcl Built-In Commands"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 tm \- Facilities for locating and loading of Tcl Modules
  13 .SH SYNOPSIS
  14 .nf
  15 \fB::tcl::tm::path add \fR?\fIpath\fR...?
  16 \fB::tcl::tm::path remove \fR?\fIpath\fR...?
  17 \fB::tcl::tm::path list\fR
  18 \fB::tcl::tm::roots \fR?\fIpath\fR...?
  19 .fi
  20 .BE
  21 .SH DESCRIPTION
  22 .PP
  23 This document describes the facilities for locating and loading Tcl
  24 Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module).
  25 The following commands are supported:
  26 .TP
  27 \fB::tcl::tm::path add \fR?\fIpath\fR...?
  28 .
  29 The paths are added at the head to the list of module paths, in order
  30 of appearance. This means that the last argument ends up as the new
  31 head of the list.
  32 .RS
  33 .PP
  34 The command enforces the restriction that no path may be an ancestor
  35 directory of any other path on the list. If any of the new paths
  36 violates this restriction an error will be raised, before any of the
  37 paths have been added. In other words, if only one path argument
  38 violates the restriction then none will be added.
  39 .PP
  40 If a path is already present as is, no error will be raised and no
  41 action will be taken.
  42 .PP
  43 Paths are searched later in the order of their appearance in the
  44 list. As they are added to the front of the list they are searched in
  45 reverse order of addition. In other words, the paths added last are
  46 looked at first.
  47 .RE
  48 .TP
  49 \fB::tcl::tm::path remove \fR?\fIpath\fR...?
  50 .
  51 Removes the paths from the list of module paths. The command silently
  52 ignores all paths which are not on the list.
  53 .TP
  54 \fB::tcl::tm::path list\fR
  55 .
  56 Returns a list containing all registered module paths, in the order
  57 that they are searched for modules.
  58 .TP
  59 \fB::tcl::tm::roots \fR?\fIpath\fR...?
  60 .
  61 Similar to \fBpath add\fR, and layered on top of it. This command
  62 takes a list of paths, extends each with
  63 .QW "\fBtcl\fIX\fB/site-tcl\fR" ,
  64 and
  65 .QW "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR" ,
  66 for major version \fIX\fR of the
  67 Tcl interpreter and minor version \fIy\fR less than or equal to the
  68 minor version of the interpreter, and adds the resulting set of paths
  69 to the list of paths to search.
  70 .RS
  71 .PP
  72 This command is used internally by the system to set up the
  73 system-specific default paths.
  74 .PP
  75 The command has been exposed to allow a build system to define
  76 additional root paths beyond those described by this document.
  77 .RE
  78 .SH "MODULE DEFINITION"
  79 .PP
  80 A Tcl Module is a Tcl Package contained in a single file, and no other
  81 files required by it. This file has to be \fBsource\fRable. In other
  82 words, a Tcl Module is always imported via:
  83 .PP
  84 .CS
  85 source module_file
  86 .CE
  87 .PP
  88 The \fBload\fR command is not directly used. This restriction is not
  89 an actual limitation, as some may believe.
  90 Ever since 8.4 the Tcl \fBsource\fR command reads only until the first
  91 ^Z character. This allows us to combine an arbitrary Tcl script with
  92 arbitrary binary data into one file, where the script processes the
  93 attached data in any it chooses to fully import and activate the
  94 package.
  95 .PP
  96 The name of a module file has to match the regular expression:
  97 .PP
  98 .CS
  99 ([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\e.tm
 100 .CE
 101 .PP
 102 The first capturing parentheses provides the name of the package, the
 103 second clause its version. In addition to matching the pattern, the
 104 extracted version number must not raise an error when used in the
 105 command:
 106 .PP
 107 .CS
 108 package vcompare $version 0
 109 .CE
 110 .SH "FINDING MODULES"
 111 .PP
 112 The directory tree for storing Tcl modules is separate from other
 113 parts of the filesystem and independent of \fBauto_path\fR.
 114 .PP
 115 Tcl Modules are searched for in all directories listed in the result
 116 of the command \fB::tcl::tm::path list\fR.
 117 This is called the \fIModule path\fR. Neither the \fBauto_path\fR nor
 118 the \fBtcl_pkgPath\fR variables are used.
 119 All directories on the module path have to obey one restriction:
 120 .RS
 121 .PP
 122 For any two directories, neither is an ancestor directory of the
 123 other.
 124 .RE
 125 .PP
 126 This is required to avoid ambiguities in package naming. If for
 127 example the two directories
 128 .QW "\fIfoo/\fR"
 129 and
 130 .QW "\fIfoo/cool\fR"
 131 were on
 132 the path a package named \fBcool::ice\fR could be found via the
 133 names \fBcool::ice\fR or \fBice\fR, the latter potentially
 134 obscuring a package named \fBice\fR, unqualified.
 135 .PP
 136 Before the search is started, the name of the requested package is
 137 translated into a partial path, using the following algorithm:
 138 .RS
 139 .PP
 140 All occurrences of
 141 .QW "\fB::\fR"
 142 in the package name are replaced by
 143 the appropriate directory separator character for the platform we are
 144 on. On Unix, for example, this is
 145 .QW "\fB/\fR" .
 146 .RE
 147 .PP
 148 Example:
 149 .RS
 150 .PP
 151 The requested package is \fBencoding::base64\fR. The generated
 152 partial path is
 153 .QW "\fIencoding/base64\fR" .
 154 .RE
 155 .PP
 156 After this translation the package is looked for in all module paths,
 157 by combining them one-by-one, first to last with the partial path to
 158 form a complete search pattern. Note that the search algorithm rejects
 159 all files where the filename does not match the regular expression
 160 given in the section \fBMODULE DEFINITION\fR. For the remaining
 161 files \fIprovide scripts\fR are generated and added to the package
 162 ifneeded database.
 163 .PP
 164 The algorithm falls back to the previous unknown handler when none of
 165 the found module files satisfy the request. If the request was
 166 satisfied the fall-back is ignored.
 167 .PP
 168 Note that packages in module form have \fIno\fR control over the
 169 \fIindex\fR and \fIprovide script\fRs entered into the package
 170 database for them.
 171 For a module file \fBMF\fR the \fIindex script\fR is always:
 172 .PP
 173 .CS
 174 package ifneeded \fBPNAME PVERSION\fR [list source \fBMF\fR]
 175 .CE
 176 .PP
 177 and the \fIprovide script\fR embedded in the above is:
 178 .PP
 179 .CS
 180 source \fBMF\fR
 181 .CE
 182 .PP
 183 Both package name \fBPNAME\fR and package version \fBPVERSION\fR are
 184 extracted from the filename \fBMF\fR according to the definition
 185 below:
 186 .PP
 187 .CS
 188 \fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm
 189 .CE
 190 .PP
 191 Where \fBPNAME\(fm\fR is the partial path of the module as defined in
 192 section \fBFINDING MODULES\fR, and translated into \fBPNAME\fR by
 193 changing all directory separators to
 194 .QW "\fB::\fR" ,
 195 and \fBmodule_path\fR is the path (from the list of paths to search)
 196 that we found the module file under.
 197 .PP
 198 Note also that we are here creating a connection between package names
 199 and paths. Tcl is case-sensitive when it comes to comparing package
 200 names, but there are filesystems which are not, like NTFS. Luckily
 201 these filesystems do store the case of the name, despite not using the
 202 information when comparing.
 203 .PP
 204 Given the above we allow the names for packages in Tcl modules to have
 205 mixed-case, but also require that there are no collisions when
 206 comparing names in a case-insensitive manner. In other words, if a
 207 package \fBFoo\fR is deployed in the form of a Tcl Module,
 208 packages like \fBfoo\fR, \fBfOo\fR, etc. are not allowed
 209 anymore.
 210 .SH "DEFAULT PATHS"
 211 .PP
 212 The default list of paths on the module path is computed by a
 213 \fBtclsh\fR as follows, where \fIX\fR is the major version of the Tcl
 214 interpreter and \fIy\fR is less than or equal to the minor version of
 215 the Tcl interpreter.
 216 .PP
 217 All the default paths are added to the module path, even those paths
 218 which do not exist. Non-existent paths are filtered out during actual
 219 searches. This enables a user to create one of the paths searched when
 220 needed and all running applications will automatically pick up any
 221 modules placed in them.
 222 .PP
 223 The paths are added in the order as they are listed below, and for
 224 lists of paths defined by an environment variable in the order they
 225 are found in the variable.
 226 .SS "SYSTEM SPECIFIC PATHS"
 227 .TP
 228 \fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR
 229 .
 230 In other words, the interpreter will look into a directory specified
 231 by its major version and whose minor versions are less than or equal
 232 to the minor version of the interpreter.
 233 .RS
 234 .PP
 235 For example for Tcl 8.4 the paths searched are:
 236 .PP
 237 .CS
 238 \fB[info library]/../tcl8/8.4\fR
 239 \fB[info library]/../tcl8/8.3\fR
 240 \fB[info library]/../tcl8/8.2\fR
 241 \fB[info library]/../tcl8/8.1\fR
 242 \fB[info library]/../tcl8/8.0\fR
 243 .CE
 244 .PP
 245 This definition assumes that a package defined for Tcl \fIX\fB.\fIy\fR
 246 can also be used by all interpreters which have the same major number
 247 \fIX\fR and a minor number greater than \fIy\fR.
 248 .RE
 249 .TP
 250 \fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR
 251 .
 252 Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
 253 or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
 254 .RS
 255 .PP
 256 This sets of paths is handled equivalently to the set coming before,
 257 except that it is anchored in \fBEXEC_PREFIX\fR.
 258 For a build with \fBPREFIX\fR = \fBEXEC_PREFIX\fR the two sets are
 259 identical.
 260 .RE
 261 .SS "SITE SPECIFIC PATHS"
 262 .TP
 263 \fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR
 264 .
 265 Note that this is always a single entry because \fIX\fR is always a
 266 specific value (the current major version of Tcl).
 267 .SS "USER SPECIFIC PATHS"
 268 .TP
 269 \fB$::env(TCL\fIX\fB_\fIy\fB_TM_PATH)\fR
 270 .
 271 A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR
 272 (Windows). This is user and site specific as this environment variable
 273 can be set not only by the user's profile, but by system configuration
 274 scripts as well.
 275 .TP
 276 \fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
 277 .
 278 Same meaning and content as the previous variable. However the use of
 279 dot '.' to separate major and minor version number makes this name
 280 less to non-portable and its use is discouraged. Support of this
 281 variable has been kept only for backward compatibility with the
 282 original specification, i.e. TIP 189.
 283 .PP
 284 These paths are seen and therefore shared by all Tcl shells in the
 285 \fB$::env(PATH)\fR of the user.
 286 .PP
 287 Note that \fIX\fR and \fIy\fR follow the general rules set out
 288 above. In other words, Tcl 8.4, for example, will look at these 10
 289 environment variables:
 290 .PP
 291 .CS
 292 \fB$::env(TCL8.4_TM_PATH)\fR  \fB$::env(TCL8_4_TM_PATH)\fR
 293 \fB$::env(TCL8.3_TM_PATH)\fR  \fB$::env(TCL8_3_TM_PATH)\fR
 294 \fB$::env(TCL8.2_TM_PATH)\fR  \fB$::env(TCL8_2_TM_PATH)\fR
 295 \fB$::env(TCL8.1_TM_PATH)\fR  \fB$::env(TCL8_1_TM_PATH)\fR
 296 \fB$::env(TCL8.0_TM_PATH)\fR  \fB$::env(TCL8_0_TM_PATH)\fR
 297 .CE
 298 .SH "SEE ALSO"
 299 package(n), Tcl Improvement Proposal #189
 300 .QW "\fITcl Modules\fR"
 301 (online at https://tip.tcl-lang.org/189.html), Tcl Improvement Proposal #190
 302 .QW "\fIImplementation Choices for Tcl Modules\fR"
 303 (online at https://tip.tcl-lang.org/190.html)
 304 .SH "KEYWORDS"
 305 modules, package
 306 .\" Local Variables:
 307 .\" mode: nroff
 308 .\" End: