teacup - TEApot Repository Client
This document is reference documentation for the TEApot client application. It assumes that the reader has read at least the TEApot Introduction, the TEApot Glossary of Terms, and possibly the TEApot Meta Data Specification.
This tool is used to manage a user's personal TEApot installation. It will also be used by administrators to manage centralized installations, if so desired.
As such it sits squarely between two distinct sets of TEApot repositories, namely:
On the one side are the installation repositories, which are the repositories packages are installed into. One of these repositories will be the default destination for doing package installations.
An installation repository is one source of packages for Tcl installations, like ActiveTcl, which allow one to invoke 'package require' to load a package from the repository. For ActiveTcl, the necessary code is already part of the tclsh's "init.tcl". For other installations, the relevant code can installed by using teacup's setup method. See also the TEApot FAQ for more information.
Please see the section Management of installation repositories for the teacup commands relevant to their direct management, and the option --at in section Common options when having to deal with installation repositories other than the default.
On the other side we have the archives, which are repositories to search when the TEApot client is asked to perform an installation. Please see the section Management of archives for the teacup commands relevant to their management.
Archives can be either local or network repositories. For local repositories both opaque and transparent repositories are acceptable.
Note however that while the above makes it possible to add an installation repository to the set of archives known to teacup this makes sense only when packages for an installation A should be drawn from a different installation B. It makes no sense whatsoever to put an installation repository A into the set of archives when A is also the destination for packages to install.
The behaviour of the application can be configured in various ways for the environment it is in, with the settings persisting across invocations. The commands for doing so, and where this configuration is stored, are explained in the section Configuration management.
Information about the available commands and their syntax is printed to the standard output.
Prints the version number of the application to the standard output.
Prints the complete teapot meta data of the application to the standard output.
The command locates the newest revision of the application in the known set of archives, retrieves it, and overwrites itself with it. The application saves itself with the extension .bak before doing the update, to allow an easy restoration in case something goes wrong.
For the unexplained option see section Options.
Installation (repositories) are the repositories packages are installed into. One of these repositories will be the default destination for doing package installations.
While ActiveTcl's tcl shell comes already prepared with all the code necessary to be able to look for and use installation repositories, most Tcl shells, especially self-built ones, do not. This command takes the path to a valid Tcl shell and then adds the appropriate code, enabling it to look for and use installation repositories as well.
This command creates a local installation repository at the directory dir. If no directory is specified then a platform-specific standard location is used:
"~/.teapot/repository"
"$USERPROFILE/Teapot/repository".
"~/Library/Application Support/ActiveState/Teapot/repository"
(Note the space between "Application" and "Support").
This command deletes the local installation repository at the directory dir. It takes care to break the connections to all shells using the repository before deleting it from the filesystem.
Create a connection between the installation repository at dir and the tcl shell. After this command is executed, the shell will search the installation repository at dir when a package is required, and the repository records the shell's location and platform information. The latter means that teacup will accept only packages compatible with the shell's platform before attempting to install a package, and it will ask the shell for the list of all packages it can use when checking if a package is already installed.
Removes the connection between the installation repository at dir and the tcl shell. From then on the shell will not search the repository when a package is required, and teacup will not check the shell anymore when installing a package.
Note that it is allowed to specify an arbitrary number of shells and repository dirs, in arbitrary order. The command will disconnect all possible pairs.
Prints either the list of shells the repository at dir is connected to, or the list of repositories the shell is using.
This command sets or queries which installation is the default installation repository.
When called with the dir specified all future calls will use the installation at that location by default.
The command always prints the data of the default installation to stdout. In this way an invocation without dir simply queries the current settings.
The archives are the repositories the packages to install are searched in and drawn from. For their management we have three commands, to list the current set, and add/remove repositories to/from the set.
This command prints a list of all the archives known to the client to stdout.
This command adds the archive at location url to the set of archives to query when searching for packages.
The url can be a path in the local filesystem, a file://-url in the local filesystem, or a http://-url referring to a network repository provided by a teapot server running on some host.
This command removes the archive at location url from the set of archives to query when searching for packages.
The url can be a path in the local filesystem, a file://-url in the local filesystem, or a http://-url referring to a network repository provided by a teapot server running on some host.
The behaviour of the application can be configured in various ways for the environment it is in, with the settings persisting across invocations. The commands for doing so, and where this configuration is stored, are explained here.
The related commands to manage the default installation and the set of archives are not explained here, but in the sections Management of installation repositories and Management of archives respectively. They use however the same underlying mechanisms as the configuration command to persist their settings.
The configurable settings are
Whether to cache the indices of remote archives or not, and where.
The timeout to use when accessing network repositories.
If or what http-proxy to use when accessing network repositories.
On Unix the configuration is stored in a platform specific directory, whereas on Windows the registry is used. The internal structure of either directory or registry tree are not part of the public API and therefore not documented.
"~/.teapot/config"
HKEY_CURRENT_USER\Software\ActiveState\TEAPOT
"~/Library/Application Support/ActiveState/Teapot/config"
(Note the space between "Application" and "Support").
The commands to access the configuration are
This command enables the caching of the index databases from remote archives on the local system. This happens by default under the directory "~/.teapot/indexcache", but this can be overridden by explicitly specifying a directory dir.
This command disables the caching of the index databases from remote archives on the local system. Existing cached indices and associated stati are not deleted, allowing their reuse if this feature is activated again.
We do not recommend to deactivate the cache, as this will make searches in network repositories slow (The query has to be passed to the repository server for execution, the result has to be transfered back, and the server can become a bottleneck due to higher load).
This command deletes all cached indices and associated stati from the local filesystem. This command fails when caching is disabled, as at that time it is not known where to look for the index files.
To get a clear disabled state clear the cache first, then disable it.
This command prints the status of local caching of remote meta data. I.e. whether this is active or not, the path used for the cached information, timestamps for the cached indices.
Query or set the host and port used for proxying. Note that even if no proxying is set here the teacup will obey a proxying configuration set in the environment and/or registry, per the Tcllib package autoproxy.
Query or set the number of seconds after which a remote operation times out. A negative value (including zero) disables the timeout, i.e. sets it to infinity.
Get and install the entity name, either the highest version, or at least version, or the exact version, and all its required dependencies (recursive). Recommended dependencies are not installed by default. The destination is either the default installation repository, or the installation repository specified via the option --at.
Assumes by default that a package is installed, however this can be overridden by explictly specifying the type of the entity with option -is.
Note: When installing a newer version of an already installed entity it is required to specify not only the name, but the version number as well. With only a name the command will find the installed version of the entity in question and therefore see no need to install anything at all.
For the options not explained below see section Options.
If a path or url is specified it is considered as a package to install directly, without retrieving it from an archive. Note however that the dependency resolution for the package in the specified file is still done through the configured archives, and all the missing dependent packages are retrieved from the archives and installed as well.
Some examples:
To get all of ActiveTcl use
teacup install ActiveState::ActiveTcl
Or, if only the packages in Tcllib are needed, use
teacup install tcllib
See the profiles command to determine what other profiles are available for the convenient installation of large bundles of packages. See the list and search commands to look up specific packages.
If you wish to get all packages we have, beyond ActiveTcl, see the update command.
Removes all or specified versions of the entity name from the chosen installation. It is possible to restrict the removal to a specific architecture of the package. It can furhter be forced to remove all packages in the target repository (by specifying neither name nor version nor architecture).
For the options not explained below see section Options.
This command is in essence a combination of
teacup list --only uninstalled
teacup list --only newer
teacup install --force
It finds all packages which are not installed locally but present in the configured archives and installs them. It further finds the highest versions of all installed packages in the configured archives and install any not yet installed locally.
By default both uninstalled and newer packages are installed, however by using the option --only the user can restrict this to either of the two.
For the options not explained here see section Options.
Prints the contents of the meta data keyword Description for package name, or name+version, as found in the configured set of archives.
For the options not explained below see section Options.
Lists all occurences of the named package in the configured set of archives. The output can be restricted to a specific version of the package, or forced to contain all packages (by specifying neither name nor version).
If a name was specified, but nothing was found the command does a case-insensitive substring search for candidate names and then re-does the operation for all found candidates. This fixes typos like 'bwidget' instead of 'BWidget', but also means that 'zlib' will find 'zlibtcl', etc.
For the options not explained here see section Options.
Limiters
Retrieve the package files for all occurences of the named package in the configured set of archives. The retrieval can be restricted to a specific version of the package, and even a specific architecture of that. It can also be forced to retrieve all packages (by specifying neither name nor version nor architecture).
For the options not explained here see section Options.
The retrieved files are placed into the directory specified via option --output, with file names constructed from the package name, version, architecture, and type of archive. If the option --output is not present the application will default to the current directory.
The name of the package archive for an entity with type T, name N, version V, and architecture A is
T-N'-V-A.EXT
where N' is derived from N by encoding the ":"-character as %3a. This is necessary to avoid problems on Windows, which does't allow ":" within filenames. The extension EXT is either tm, or zip, depending on the file format. This last information is currently not directly available in the meta data.
Also note that the architecture A may contain dashes (-) as well.
Prints a list of all profile packages found in the configured set of archives to stdout. This is a shorthand for
teapot search -has Profile
For the options not explained here see section Options.
Print a lists of all entities found in the configured set of archives to stdout which match the conditions of the query.
For the options not explained here see section Options.
The simplest possible query consists of a single word, for example FOO. This will run a case-insensitive substring search for the name FOO.
A more complex query consists of a series of options interspersed with regular words as arguments. The fundamental queries are
All these conditions imply that a matching entity also has the specified key in their meta data.
Composite queries, also known as complex queries, can be put together with the operators -a, -and, -o, and -or ("and", and "or"). The operators -a and -and are equivalent and are binding tighter than the operator -o (and its equivalent operator -or). This can be changed by grouping expressions with round parentheses, i.e. "(", and ")".
Note that parentheses are often special to the shell used to invoke teacup, i.e. they may require quoting to be passed unchanged to teacup.
All operators can be also used with and without their dash (-). The only exceptions are the short combinators -a and -o. As example, the two following queries are equivalent:
teacup search -in subject hashing teacup search in subject hashing
Similarly the simple case-insensitive substring search shown at the beginning, i.e.
teacup search FOO
internally expands to a long form using Tcl's advanced regular expressions:
teacup search -re name '(?i)FOO'
Prints a list of all keywords found in the meta data of all instances stored in the configured set of archives.
For the options not explained here see section Options.
Show the log of installed/removed packages of either the default installation repository, or the repository pointed to by --at.
Normally the whole log is shown, but this can be restricted to either the last n entries, or the entries made after a given date and time (timestamp). The restrictions cannot be combined. When specifying more than one the last one will be used.
The log will be printed to the standard output in a simple tabular format, with the oldest entries coming last. I.e. the newest entries can be found at the top of the log.
The argument n has to be an integer number greater than zero.
The argument timestamp may have one of the following forms:
Unix epoch value.
ISO DATE+TIME
ISO DATE only, the time defaults to midnight.
ISO TIME only, the date defaults to today.
An example of the output format is
2007-03-02 14:16:12 1 remove package udp 1.0.8 linux-glibc2.2-ix86 2007-03-02 14:10:04 1 install package udp 1.0.8 linux-glibc2.2-ix86 2007-03-02 14:09:50 1 install package Diagrams 0.2 tcl
The columns are DATE, TIME, SERIAL, ACTION, ENTITY, NAME, VERSION, ARCH; in this order.
are the date & time when the log entry was made.
is a serial number which distinguishes entries should they happen to be made in the same second. It is counted from 1 up, per invocation of teacup.
is either install, or remove.
is the type of the entity installed/removed, currently either package or application.
identify the entity more, by name, version and architecture, also known as platform.
The lengths and positions of the columns SERIAL, ENTITY, NAME, VERSION, and ARCH are dynamically determined from the entries printed. The other columns all have fixed lengths, but may change position.
10 chars.
8 chars.
7 chars.
Purges the log of installed/removed packages of either the default installation repository, or the repository pointed to by --at. Normally the whole log is purged, but this can be restricted to all but the last n entries, or all but the entries made after a given date and time (timestamp). I.e. either the last n entries are kept in the log, or the entries made after the given date and time are kept in the log. The restrictions cannot be combined. When specifying more than one the last one will be used.
The argument n has to be an integer number greater than zero.
The argument timestamp may have the same forms as described for log show above.
The client application currently supports a number of predefined searches, shown below, and free-form searches over the entire stored meta data via the subcommand search. As part of the list of predefined searches we also demonstrate how they could be implemented in terms of search.
search -is entity -a -eq name name -a -eq version version
search -eq entity entity -a -eq name name -a -eq version version
Show all entities of type entity with the specified exact name and exact version. For example:
list --is application base-tcl 8.4 search -is application -a -eq Name base-tcl -a -eq Version 8.4 search -eq Entity application -a -eq Name base-tcl -a -eq Version 8.4
search -is entity -a -eq Name name
search -eq Entity entity -a -eq Name name
Show all entities of type entity with the specified exact name, regardless of version. For example:
list --is package zlibtcl search -is package -a -eq Name zlibtcl search -eq Entity package -a -eq Name zlibtcl
search -is entity
search -eq Entity entity
Show all entities of type entity, regardless of name or version. For example:
list --is package search -is package search -eq Entity package
search -eq Name name -a -eq Version version
Show all entities with the specified exact name and exact version, regardless of entity-type. For example:
list XOTcl 1.3.5 search -eq Name XOTcl -a -eq Version 1.3.5
search -eq Name name
Show all entities with the specified exact name, regardless of version or entity-type. For example:
list XOTcl search -eq name XOTcl
Show all entities regardless of name, version or entity-type.
Show all entities which are known to the archives, are not installed locally, and can be installed locally.
Show all entities which are installed locally and for which we can find newer versions in the archives.
search -has Profile
Show all entities regardless of name, version or entity-type, which are profiles.
The install command internally performs searches as well, similar to the list searches above, however the architecture is implicitly constrained to the architectures acceptable to selected installation repository, and the highest possible version is selected if no exact version was requested.
In contrast to install the method get will retrieve all possible versions, and architectures.
This document, and the application it describes, will undoubtedly contain bugs and other problems. Please report such at the ActiveState ActiveTcl Bug Tracker. The relevant component is teapot. Please also report any ideas for enhancements you may have for either application and/or documentation.
The version number of the teacup application with the problem in question can be queried with the command version, as explained in section General inquiries and getting new revisions.
Copyright © 2006-2008 ActiveState Software Inc.