2. EL 8
  3. tcl-doc
  4. tm(n)

Scroll to navigation

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





NAME


tm - Facilities for locating and loading of Tcl Modules






SYNOPSIS


::tcl::tm::path add ?path...?
::tcl::tm::path remove ?path...?
::tcl::tm::path list
::tcl::tm::roots ?path...?








DESCRIPTION


This document describes the facilities for locating and loading
    Tcl Modules (see MODULE DEFINITION for the definition of a Tcl
    Module). The following commands are supported:



  
::tcl::tm::path add ?path...?

  
The paths are added at the head to the list of module paths, in order of
      appearance. This means that the last argument ends up as the new head of
      the list.






The command enforces the restriction that no path may be an
    ancestor directory of any other path on the list. If any of the new paths
    violates this restriction an error will be raised, before any of the paths
    have been added. In other words, if only one path argument violates the
    restriction then none will be added.


If a path is already present as is, no error will be raised and no
    action will be taken.


Paths are searched later in the order of their appearance in the
    list. As they are added to the front of the list they are searched in
    reverse order of addition. In other words, the paths added last are looked
    at first.





  
::tcl::tm::path remove ?path...?

  
Removes the paths from the list of module paths. The command silently
      ignores all paths which are not on the list.

  
::tcl::tm::path list

  
Returns a list containing all registered module paths, in the order that
      they are searched for modules.

  
::tcl::tm::roots ?path...?

  
Similar to path add, and layered on top of it. This command takes a
      list of paths, extends each with
      “tclX/site-tcl”, and
      “tclX/X.y”, for
      major version X of the Tcl interpreter and minor version y
      less than or equal to the minor version of the interpreter, and adds the
      resulting set of paths to the list of paths to search.






This command is used internally by the system to set up the
    system-specific default paths.


The command has been exposed to allow a build system to define
    additional root paths beyond those described by this document.








MODULE DEFINITION


A Tcl Module is a Tcl Package contained in a single file, and no
    other files required by it. This file has to be sourceable. In other
    words, a Tcl Module is always imported via:






source module_file




The load command is not directly used. This restriction is
    not an actual limitation, as some may believe. Ever since 8.4 the Tcl
    source command reads only until the first ^Z character. This allows
    us to combine an arbitrary Tcl script with arbitrary binary data into one
    file, where the script processes the attached data in any it chooses to
    fully import and activate the package.


The name of a module file has to match the regular expression:






([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\.tm




The first capturing parentheses provides the name of the package,
    the second clause its version. In addition to matching the pattern, the
    extracted version number must not raise an error when used in the
  command:






package vcompare $version 0








FINDING MODULES


The directory tree for storing Tcl modules is separate from other
    parts of the filesystem and independent of auto_path.


Tcl Modules are searched for in all directories listed in the
    result of the command ::tcl::tm::path list. This is called the
    Module path. Neither the auto_path nor the tcl_pkgPath
    variables are used. All directories on the module path have to obey one
    restriction:




For any two directories, neither is an ancestor directory of the
    other.




This is required to avoid ambiguities in package naming. If for
    example the two directories “foo/” and
    “foo/cool” were on the path a package named
    cool::ice could be found via the names cool::ice or
    ice, the latter potentially obscuring a package named ice,
    unqualified.


Before the search is started, the name of the requested package is
    translated into a partial path, using the following algorithm:




All occurrences of “::” in the package name
    are replaced by the appropriate directory separator character for the
    platform we are on. On Unix, for example, this is
  “/”.




Example:




The requested package is encoding::base64. The generated
    partial path is “encoding/base64”.




After this translation the package is looked for in all module
    paths, by combining them one-by-one, first to last with the partial path to
    form a complete search pattern. Note that the search algorithm rejects all
    files where the filename does not match the regular expression given in the
    section MODULE DEFINITION. For the remaining files provide
    scripts are generated and added to the package ifneeded database.


The algorithm falls back to the previous unknown handler when none
    of the found module files satisfy the request. If the request was satisfied
    the fall-back is ignored.


Note that packages in module form have no control over the
    index and provide scripts entered into the package database
    for them. For a module file MF the index script is always:






package ifneeded PNAME PVERSION [list source MF]




and the provide script embedded in the above is:






source MF




Both package name PNAME and package version PVERSION
    are extracted from the filename MF according to the definition
  below:






MF = /module_path/PNAME′-PVERSION.tm




Where PNAME′ is the partial path of the module as
    defined in section FINDING MODULES, and translated into PNAME
    by changing all directory separators to “::”, and
    module_path is the path (from the list of paths to search) that we
    found the module file under.


Note also that we are here creating a connection between package
    names and paths. Tcl is case-sensitive when it comes to comparing package
    names, but there are filesystems which are not, like NTFS. Luckily these
    filesystems do store the case of the name, despite not using the information
    when comparing.


Given the above we allow the names for packages in Tcl modules to
    have mixed-case, but also require that there are no collisions when
    comparing names in a case-insensitive manner. In other words, if a package
    Foo is deployed in the form of a Tcl Module, packages like
    foo, fOo, etc. are not allowed anymore.






DEFAULT PATHS


The default list of paths on the module path is computed by a
    tclsh as follows, where X is the major version of the Tcl
    interpreter and y is less than or equal to the minor version of the
    Tcl interpreter.


All the default paths are added to the module path, even those
    paths which do not exist. Non-existent paths are filtered out during actual
    searches. This enables a user to create one of the paths searched when
    needed and all running applications will automatically pick up any modules
    placed in them.


The paths are added in the order as they are listed below, and for
    lists of paths defined by an environment variable in the order they are
    found in the variable.




SYSTEM SPECIFIC PATHS



  

  
In other words, the interpreter will look into a directory specified by
      its major version and whose minor versions are less than or equal to the
      minor version of the interpreter.






For example for Tcl 8.4 the paths searched are:






[info library]/../tcl8/8.4
[info library]/../tcl8/8.3
[info library]/../tcl8/8.2
[info library]/../tcl8/8.1
[info library]/../tcl8/8.0




This definition assumes that a package defined for Tcl
    X.y can also be used by all interpreters which have the
    same major number X and a minor number greater than y.





  

  
Where EXEC is file normalize [info nameofexecutable]/../lib
      or file normalize [::tcl::pkgconfig get libdir,runtime]






This sets of paths is handled equivalently to the set coming
    before, except that it is anchored in EXEC_PREFIX. For a build with
    PREFIX = EXEC_PREFIX the two sets are identical.








SITE SPECIFIC PATHS



  

  
Note that this is always a single entry because X is always a
      specific value (the current major version of Tcl).








USER SPECIFIC PATHS



  
$::env(TCLX_y_TM_PATH)

  
A list of paths, separated by either : (Unix) or ;
      (Windows). This is user and site specific as this environment variable can
      be set not only by the user's profile, but by system configuration scripts
      as well.

  
$::env(TCLX.y_TM_PATH)

  
Same meaning and content as the previous variable. However the use of dot
      '.' to separate major and minor version number makes this name less to
      non-portable and its use is discouraged. Support of this variable has been
      kept only for backward compatibility with the original specification, i.e.
      TIP 189.




These paths are seen and therefore shared by all Tcl shells in the
    $::env(PATH) of the user.


Note that X and y follow the general rules set out
    above. In other words, Tcl 8.4, for example, will look at these 10
    environment variables:






$::env(TCL8.4_TM_PATH)  $::env(TCL8_4_TM_PATH)
$::env(TCL8.3_TM_PATH)  $::env(TCL8_3_TM_PATH)
$::env(TCL8.2_TM_PATH)  $::env(TCL8_2_TM_PATH)
$::env(TCL8.1_TM_PATH)  $::env(TCL8_1_TM_PATH)
$::env(TCL8.0_TM_PATH)  $::env(TCL8_0_TM_PATH)










SEE ALSO


package(n), Tcl Improvement Proposal #189 “Tcl
    Modules” (online at http://tip.tcl.tk/189.html), Tcl Improvement
    Proposal #190 “Implementation Choices for Tcl Modules”
    (online at http://tip.tcl.tk/190.html)






KEYWORDS


modules, package







  

    8.5
    Tcl