diff options
Diffstat (limited to 'doc/tm.n')
| -rw-r--r-- | doc/tm.n | 135 |
1 files changed, 89 insertions, 46 deletions
@@ -1,31 +1,31 @@ '\" -'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" 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. '\" -'\" RCS: @(#) $Id: tm.n,v 1.5 2004/11/12 09:01:25 das Exp $ -'\" -.so man.macros .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\fR \fBadd\fR \fIpath\fR... -\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR... -\fB::tcl::tm::path\fR \fBlist\fR -\fB::tcl::tm::roots\fR \fIpath\fR... +\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. The following commands are supported: +Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module). +The following commands are supported: .TP -\fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR... +\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. @@ -46,18 +46,24 @@ reverse order of addition. In other words, the paths added last are looked at first. .RE .TP -\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR... +\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\fR \fBlist\fR +\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... +\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 "\fBtcl\fIX\fB/site-tcl\fR", -and "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR", for major version \fIX\fR of the +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. @@ -66,13 +72,15 @@ to the list of paths to search. 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 buildsystem to define +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 @@ -86,19 +94,21 @@ 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:]].*)\\.tm +([_[: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 -.PP .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 @@ -107,27 +117,41 @@ 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: -.IP +.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 "\fIfoo/\fR" and "\fIfoo/cool\fR" were on +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: -.IP -All occurrences of "\fB::\fR" in the package name are replaced by +.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 "\fB/\fR". +on. On Unix, for example, this is +.QW "\fB/\fR" . +.RE .PP Example: -.IP +.RS +.PP The requested package is \fBencoding::base64\fR. The generated -partial path is "\fIencoding/base64\fR" +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 @@ -145,10 +169,13 @@ 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 @@ -156,13 +183,15 @@ source \fBMF\fR 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'\fR-\fBPVERSION\fR.tm +\fBMF\fR = /module_path/\fBPNAME\(fm\fR-\fBPVERSION\fR.tm .CE .PP -Where \fBPNAME'\fR is the partial path of the module as defined in -section \fBFINDING MODULES\fR, and translated into \fB\fRPNAME by -changing all directory separators to "\fB::\fR", +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 @@ -179,6 +208,7 @@ 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 @@ -196,12 +226,14 @@ 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 @@ -216,6 +248,7 @@ can also be used by all interpreters which have the same major number .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 @@ -228,38 +261,48 @@ identical. .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 +\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. -.RS +.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 5 +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.3_TM_PATH)\fR -\fB$::env(TCL8.2_TM_PATH)\fR -\fB$::env(TCL8.1_TM_PATH)\fR -\fB$::env(TCL8.0_TM_PATH)\fR +\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 -.RE - .SH "SEE ALSO" -package(n), Tcl Improvement Proposal #189 "\fITcl Modules\fR" (online -at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 -"\fIImplementation Choices for Tcl Modules\fR" (online at -http://tip.tcl.tk/190.html) - - +package(n), Tcl Improvement Proposal #189 +.QW "\fITcl Modules\fR" +(online at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 +.QW "\fIImplementation Choices for Tcl Modules\fR" +(online at http://tip.tcl.tk/190.html) .SH "KEYWORDS" modules, package +.\" Local Variables: +.\" mode: nroff +.\" End: |