309 lines
10 KiB
Plaintext
309 lines
10 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 2004-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
.TH tm n 8.5 Tcl "Tcl Built-In Commands"
|
|
.so man.macros
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
tm \- Facilities for locating and loading of Tcl Modules
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB::tcl::tm::path add \fR?\fIpath\fR...?
|
|
\fB::tcl::tm::path remove \fR?\fIpath\fR...?
|
|
\fB::tcl::tm::path list\fR
|
|
\fB::tcl::tm::roots \fR?\fIpath\fR...?
|
|
.fi
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
This document describes the facilities for locating and loading Tcl
|
|
Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module).
|
|
The following commands are supported:
|
|
.TP
|
|
\fB::tcl::tm::path add \fR?\fIpath\fR...?
|
|
.
|
|
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.
|
|
.RS
|
|
.PP
|
|
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.
|
|
.PP
|
|
If a path is already present as is, no error will be raised and no
|
|
action will be taken.
|
|
.PP
|
|
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.
|
|
.RE
|
|
.TP
|
|
\fB::tcl::tm::path remove \fR?\fIpath\fR...?
|
|
.
|
|
Removes the paths from the list of module paths. The command silently
|
|
ignores all paths which are not on the list.
|
|
.TP
|
|
\fB::tcl::tm::path list\fR
|
|
.
|
|
Returns a list containing all registered module paths, in the order
|
|
that they are searched for modules.
|
|
.TP
|
|
\fB::tcl::tm::roots \fR?\fIpath\fR...?
|
|
.
|
|
Similar to \fBpath add\fR, and layered on top of it. This command
|
|
takes a list of paths, extends each with
|
|
.QW "\fBtcl\fIX\fB/site-tcl\fR" ,
|
|
and
|
|
.QW "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR" ,
|
|
for major version \fIX\fR of the
|
|
Tcl interpreter and minor version \fIy\fR 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.
|
|
.RS
|
|
.PP
|
|
This command is used internally by the system to set up the
|
|
system-specific default paths.
|
|
.PP
|
|
The command has been exposed to allow a build system to define
|
|
additional root paths beyond those described by this document.
|
|
.RE
|
|
.SH "MODULE DEFINITION"
|
|
.PP
|
|
A Tcl Module is a Tcl Package contained in a single file, and no other
|
|
files required by it. This file has to be \fBsource\fRable. In other
|
|
words, a Tcl Module is always imported via:
|
|
.PP
|
|
.CS
|
|
source module_file
|
|
.CE
|
|
.PP
|
|
The \fBload\fR command is not directly used. This restriction is not
|
|
an actual limitation, as some may believe.
|
|
Ever since 8.4 the Tcl \fBsource\fR 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.
|
|
.PP
|
|
The name of a module file has to match the regular expression:
|
|
.PP
|
|
.CS
|
|
([_[:alpha:]][:_[:alnum:]]*)-([[:digit:]].*)\e.tm
|
|
.CE
|
|
.PP
|
|
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:
|
|
.PP
|
|
.CS
|
|
package vcompare $version 0
|
|
.CE
|
|
.SH "FINDING MODULES"
|
|
.PP
|
|
The directory tree for storing Tcl modules is separate from other
|
|
parts of the filesystem and independent of \fBauto_path\fR.
|
|
.PP
|
|
Tcl Modules are searched for in all directories listed in the result
|
|
of the command \fB::tcl::tm::path list\fR.
|
|
This is called the \fIModule path\fR. Neither the \fBauto_path\fR nor
|
|
the \fBtcl_pkgPath\fR variables are used.
|
|
All directories on the module path have to obey one restriction:
|
|
.RS
|
|
.PP
|
|
For any two directories, neither is an ancestor directory of the
|
|
other.
|
|
.RE
|
|
.PP
|
|
This is required to avoid ambiguities in package naming. If for
|
|
example the two directories
|
|
.QW "\fIfoo/\fR"
|
|
and
|
|
.QW "\fIfoo/cool\fR"
|
|
were on
|
|
the path a package named \fBcool::ice\fR could be found via the
|
|
names \fBcool::ice\fR or \fBice\fR, the latter potentially
|
|
obscuring a package named \fBice\fR, unqualified.
|
|
.PP
|
|
Before the search is started, the name of the requested package is
|
|
translated into a partial path, using the following algorithm:
|
|
.RS
|
|
.PP
|
|
All occurrences of
|
|
.QW "\fB::\fR"
|
|
in the package name are replaced by
|
|
the appropriate directory separator character for the platform we are
|
|
on. On Unix, for example, this is
|
|
.QW "\fB/\fR" .
|
|
.RE
|
|
.PP
|
|
Example:
|
|
.RS
|
|
.PP
|
|
The requested package is \fBencoding::base64\fR. The generated
|
|
partial path is
|
|
.QW "\fIencoding/base64\fR" .
|
|
.RE
|
|
.PP
|
|
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 \fBMODULE DEFINITION\fR. For the remaining
|
|
files \fIprovide scripts\fR are generated and added to the package
|
|
ifneeded database.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Note that packages in module form have \fIno\fR control over the
|
|
\fIindex\fR and \fIprovide script\fRs entered into the package
|
|
database for them.
|
|
For a module file \fBMF\fR the \fIindex script\fR is always:
|
|
.PP
|
|
.CS
|
|
package ifneeded \fBPNAME PVERSION\fR [list source \fBMF\fR]
|
|
.CE
|
|
.PP
|
|
and the \fIprovide script\fR embedded in the above is:
|
|
.PP
|
|
.CS
|
|
source \fBMF\fR
|
|
.CE
|
|
.PP
|
|
Both package name \fBPNAME\fR and package version \fBPVERSION\fR are
|
|
extracted from the filename \fBMF\fR according to the definition
|
|
below:
|
|
.PP
|
|
.CS
|
|
\fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm
|
|
.CE
|
|
.PP
|
|
Where \fBPNAME\(fm\fR is the partial path of the module as defined in
|
|
section \fBFINDING MODULES\fR, and translated into \fBPNAME\fR by
|
|
changing all directory separators to
|
|
.QW "\fB::\fR" ,
|
|
and \fBmodule_path\fR is the path (from the list of paths to search)
|
|
that we found the module file under.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 \fBFoo\fR is deployed in the form of a Tcl Module,
|
|
packages like \fBfoo\fR, \fBfOo\fR, etc. are not allowed
|
|
anymore.
|
|
.SH "DEFAULT PATHS"
|
|
.PP
|
|
The default list of paths on the module path is computed by a
|
|
\fBtclsh\fR as follows, where \fIX\fR is the major version of the Tcl
|
|
interpreter and \fIy\fR is less than or equal to the minor version of
|
|
the Tcl interpreter.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.SS "SYSTEM SPECIFIC PATHS"
|
|
.TP
|
|
\fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR
|
|
.
|
|
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.
|
|
.RS
|
|
.PP
|
|
For example for Tcl 8.4 the paths searched are:
|
|
.PP
|
|
.CS
|
|
\fB[info library]/../tcl8/8.4\fR
|
|
\fB[info library]/../tcl8/8.3\fR
|
|
\fB[info library]/../tcl8/8.2\fR
|
|
\fB[info library]/../tcl8/8.1\fR
|
|
\fB[info library]/../tcl8/8.0\fR
|
|
.CE
|
|
.PP
|
|
This definition assumes that a package defined for Tcl \fIX\fB.\fIy\fR
|
|
can also be used by all interpreters which have the same major number
|
|
\fIX\fR and a minor number greater than \fIy\fR.
|
|
.RE
|
|
.TP
|
|
\fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR
|
|
.
|
|
Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
|
|
or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
|
|
.RS
|
|
.PP
|
|
This sets of paths is handled equivalently to the set coming before,
|
|
except that it is anchored in \fBEXEC_PREFIX\fR.
|
|
For a build with \fBPREFIX\fR = \fBEXEC_PREFIX\fR the two sets are
|
|
identical.
|
|
.RE
|
|
.SS "SITE SPECIFIC PATHS"
|
|
.TP
|
|
\fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR
|
|
.
|
|
Note that this is always a single entry because \fIX\fR is always a
|
|
specific value (the current major version of Tcl).
|
|
.SS "USER SPECIFIC PATHS"
|
|
.TP
|
|
\fB$::env(TCL\fIX\fB_\fIy\fB_TM_PATH)\fR
|
|
.
|
|
A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR
|
|
(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.
|
|
.TP
|
|
\fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
|
|
.
|
|
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.
|
|
.PP
|
|
These paths are seen and therefore shared by all Tcl shells in the
|
|
\fB$::env(PATH)\fR of the user.
|
|
.PP
|
|
Note that \fIX\fR and \fIy\fR follow the general rules set out
|
|
above. In other words, Tcl 8.4, for example, will look at these 10
|
|
environment variables:
|
|
.PP
|
|
.CS
|
|
\fB$::env(TCL8.4_TM_PATH)\fR \fB$::env(TCL8_4_TM_PATH)\fR
|
|
\fB$::env(TCL8.3_TM_PATH)\fR \fB$::env(TCL8_3_TM_PATH)\fR
|
|
\fB$::env(TCL8.2_TM_PATH)\fR \fB$::env(TCL8_2_TM_PATH)\fR
|
|
\fB$::env(TCL8.1_TM_PATH)\fR \fB$::env(TCL8_1_TM_PATH)\fR
|
|
\fB$::env(TCL8.0_TM_PATH)\fR \fB$::env(TCL8_0_TM_PATH)\fR
|
|
.CE
|
|
.SH "SEE ALSO"
|
|
package(n), Tcl Improvement Proposal #189
|
|
.QW "\fITcl Modules\fR"
|
|
(online at https://tip.tcl-lang.org/189.html), Tcl Improvement Proposal #190
|
|
.QW "\fIImplementation Choices for Tcl Modules\fR"
|
|
(online at https://tip.tcl-lang.org/190.html)
|
|
.SH "KEYWORDS"
|
|
modules, package
|
|
.\" Local Variables:
|
|
.\" mode: nroff
|
|
.\" End:
|