teacup(n) 1.0 tpm "TEA Package Management"
Name
teacup - TEApot Repository Client
Table Of Contents
Synopsis
- teacup help
- teacup version
- teacup who
- teacup update-self ?-v?
- teacup setup shell
- teacup create ?dir?
- teacup delete dir
- teacup link make dir shell
- teacup link cut (dir|shell) (dir|shell) ...
- teacup link info dir|shell
- teacup default ?dir?
- teacup archive list
- teacup archive add url
- teacup archive remove url
- teacup cache on ?dir?
- teacup cache off
- teacup cache clear
- teacup cache status
- teacup proxy ?host port?
- teacup timeout ?seconds?
- teacup install ?-v? ?--timeout sec? ?--http-proxy host:port? ?--dry-run? ?--force? ?--at dir? ?--with-recommends? (url | path | (name ??-exact? version? ?-is entity?))
- teacup remove ?--dry-run? ?--at dir? ?--is entity? ?name ?version ?architecture???
- teacup update ?-v? ?--timeout sec? ?--http-proxy host:port? ?--dry-run? ?--only uninstalled|newer|unknown|update? ?--at dir?
- teacup describe ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--is entity? ?--all? name ?version ?arch??
- teacup list ?-v? ?--timeout sec? ?--http-proxy host:port? ?--all-platforms? ?--at-default? ?--at dir? ?--is entity? ?--as csv|profile|table? ?--only uninstalled|newer|unknown|update? ?name ?version??
- teacup get ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--is entity? ?--output outdir? ?name ?version ?architecture???
- teacup profiles ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir?
- teacup search ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--as csv|profile|table? query...
- teacup keys ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir?
- teacup log show ?-l|--last n? ?-s|--since timestamp? ?--at dir?
- teacup log purge ?--keep-last n? ?--keep-since timestamp? ?--at dir?
- teacup verify ?-v? ?--at dir?
- teacup regenerate ?--at dir?
Description
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.
OVERVIEW
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.
Commands
General inquiries and getting new revisions
- teacup help
-
Information about the available commands and their syntax is printed to the standard output.
- teacup version
-
Prints the version number of the application to the standard output.
- teacup who
-
Prints the complete teapot meta data of the application to the standard output.
- teacup update-self ?-v?
-
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.
Management of installation repositories
Installation (repositories) are the repositories packages are installed into. One of these repositories will be the default destination for doing package installations.
- teacup setup shell
-
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.
- teacup create ?dir?
-
This command creates a local installation repository at the directory dir. If no directory is specified then a platform-specific standard location is used:
- Unix
-
"~/.teapot/repository"
- Windows
-
"$USERPROFILE/Teapot/repository".
- OS X
-
"~/Library/Application Support/ActiveState/Teapot/repository"
(Note the space between "Application" and "Support").
- teacup delete dir
-
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.
- teacup link make dir shell
-
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.
- teacup link cut (dir|shell) (dir|shell) ...
-
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.
- teacup link info dir|shell
-
Prints either the list of shells the repository at dir is connected to, or the list of repositories the shell is using.
- teacup default ?dir?
-
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.
Management of archives
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.
- teacup archive list
-
This command prints a list of all the archives known to the client to stdout.
- teacup archive add url
-
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.
- teacup archive remove url
-
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.
Configuration management
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.
- Unix
-
"~/.teapot/config"
- Windows
-
HKEY_CURRENT_USER\Software\ActiveState\TEAPOT
- OS X
-
"~/Library/Application Support/ActiveState/Teapot/config"
(Note the space between "Application" and "Support").
The commands to access the configuration are
- teacup cache on ?dir?
-
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.
- teacup cache off
-
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).
- teacup cache clear
-
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.
- teacup cache status
-
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.
- teacup proxy ?host port?
-
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.
- teacup timeout ?seconds?
-
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.
Package management
- teacup install ?-v? ?--timeout sec? ?--http-proxy host:port? ?--dry-run? ?--force? ?--at dir? ?--with-recommends? (url | path | (name ??-exact? version? ?-is entity?))
-
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.
- teacup remove ?--dry-run? ?--at dir? ?--is entity? ?name ?version ?architecture???
-
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.
- teacup update ?-v? ?--timeout sec? ?--http-proxy host:port? ?--dry-run? ?--only uninstalled|newer|unknown|update? ?--at dir?
-
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.
-
- teacup describe ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--is entity? ?--all? name ?version ?arch??
-
Prints the contents of the meta data keyword Description for package name, or name+version, as found in the configured set of archives.
The output can be restricted to a specific version or architecture of the package. If no architecture was specified the command will consider only instances for the current architecture. Using the string ALL as architecture will cause description of all instances regardless of architecture.
For the options not explained below see section Options.
- teacup list ?-v? ?--timeout sec? ?--http-proxy host:port? ?--all-platforms? ?--at-default? ?--at dir? ?--is entity? ?--as csv|profile|table? ?--only uninstalled|newer|unknown|update? ?name ?version??
-
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
- teacup get ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--is entity? ?--output outdir? ?name ?version ?architecture???
-
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.
- teacup profiles ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir?
-
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.
- teacup search ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir? ?--as csv|profile|table? query...
-
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'
- teacup keys ?-v? ?--timeout sec? ?--http-proxy host:port? ?--at-default? ?--at dir?
-
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.
- teacup log show ?-l|--last n? ?-s|--since timestamp? ?--at dir?
-
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:
- INTEGER
-
Unix epoch value.
- YYYY-MM-DD HH:MM:SS
-
ISO DATE+TIME
- YYYY-MM-DD
-
ISO DATE only, the time defaults to midnight.
- HH:MM:SS
-
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.
- DATE, and TIME
-
are the date & time when the log entry was made.
- SERIAL
-
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.
- ACTION
-
is either install, or remove.
- ENTITY
-
is the type of the entity installed/removed, currently either package or application.
- NAME, VERSION, and ARCH
-
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.
- DATE
-
10 chars.
- TIME
-
8 chars.
- ACTION
-
7 chars.
- teacup log purge ?--keep-last n? ?--keep-since timestamp? ?--at dir?
-
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.
Trouble Shooting
While most of the introspection commands found in the management sections are useful when trying to determine the source of some trouble, there are two commands which are explicitly just for trouble-shooting.
- teacup verify ?-v? ?--at dir?
-
This command goes through the specified local repository and checks it for consistency. I.e. are all the packages listed in the database found in the filesystem and vice versa, are the necessary package index files present, etc.
- teacup regenerate ?--at dir?
-
This command checks that the Consolidated Local Index of Packages is not broken, and repairs it if it was. This is a "pkgIdex.tcl" file maintained by teacup in the various "lib/" directories of a repository to quickly source the indices of all the installed packages.
Searching for packages and other things
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.
- list --is entity name version
-
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
- list --is entity name
-
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
- list --is entity
-
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
- list name version
-
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
- list name
-
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
- list
-
Show all entities regardless of name, version or entity-type.
- list --only uninstalled
-
Show all entities which are known to the archives, are not installed locally, and can be installed locally.
- list --only newer
-
Show all entities which are installed locally and for which we can find newer versions in the archives.
- profiles
-
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.
BUGS, IDEAS, FEEDBACK
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
Copyright © 2006-2008 ActiveState Software Inc.