Product Documentation

TDK 4.1 Documentation

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

teacup(n) 1.0 tpm "TEA Package Management"

NAME

teacup - TEApot Repository Client

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    OVERVIEW
    Commands
        General inquiries and getting new revisions
        Management of installation repositories
        Management of archives
        Configuration management
        Package management
        Common options
    Searching for packages and other things
    BUGS, IDEAS, FEEDBACK
    SEE ALSO
    KEYWORDS
    COPYRIGHT

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?

teacup list ?-v? ?--timeout sec? ?--http-proxy host:port? ?--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?

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 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.

--force: Ensures the installation of the package even if the declared dependencies could not be met, i.e. if one or more required packages are not found in the set of configured archives.

This option has no effect if teacup decided that there was no need to install an entity, i.e. when the entity is already installed. It is there to overcome missing dependencies, not to force the installation of an already installed entity.
--with-recommends: Forces the handling of recommended dependencies as if they were required dependencies, i.e. forces their installation.

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?

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.

--all: causes printing of all meta data for the package in question.

teacup list ?-v? ?--timeout sec? ?--http-proxy host:port? ?--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

--only unknown
--only uninstalled: If this option is specified the tool will remove all entities from the output which are known to be installed in the installation repository, and all which cannot be installed (wrong architecture, and profiles), leaving only those entities in the output which can be installed locally, but are not.

Note that the command will look not only at the installation repository itself for installed packages, but also query the tcl shells connected to that repository.
--only update
--only newer: If this option is specified the tool will remove all entities from the output which are not installed in the installation repository, all which cannot be installed (wrong architecture, and profiles), and all those whose version number is less or equal to their installed version, leaving only those entities in the output which are installed and for which a newer version is available in the archives.

Note that the command will look not only at the installation repository itself for installed packages, but also query the tcl shells connected to that repository.

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

-is ENTITY: The entity is of type ENTITY.
-nis ENTITY: The entity is not of type ENTITY.
-has KEY: The entity has key in its meta data.
-nhas KEY: The entity does not have the key in its meta data.
-eq KEY VAL: The entity's value for key is equal to VAL.
-re KEY PAT: The entity's value for key matches regexp pattern.
-glob KEY PAT: The entity's value for key matches glob pattern.
-in KEY VAL: The entity's value for key is list containing the value
-ne KEY VAL
-nre KEY PAT
-nglob KEY PAT
-ni KEY PAT: negations of the four previous conditions
-lt KEY VAL: The entity's value for key is less than VAL.
-gt KEY VAL: The entity's value for key is greater than VAL.
-le KEY VAL: The entity's value for key is less than or equal to VAL.
-ge KEY VAL: The entity's value for key is greater than or equal to VAL.

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.

Common options

--as profile|table|csv: This option determines the format of the output for list and search commands. By default a human readable table it can be switched to be either a .tm profile package listing all found instances as its dependencies, or a table of comma-separated values (csv).
--at dir: This option causes the application to use the local installation at dir instead of the default installation. I.e. it can be used instead of --at-default.
--at-default: This option causes the application to use the local default installation instead of the configured set of archives.
--dry-run: This option is like make -n. It causes the application to simulate the requested actions, but to not change any state.
--http-proxy host:port: This option overrides all proxy settings from environment, teacup configuration, etc. with a setting just for the current command.
--is entity: This option causes the application to restrict itself to entities of the specified type. If this option is not specified actions influence all entities matching the name, version, etc., independent of their type.
--timeout seconds: This option forces the use of a specific timeout when retrieving information from a remote repository. It overrides the settings from the configuration, and the hardwired defaults. A value <= 0 disables timeouts, allowing for infinite waiting.
-v: This option activates a more verbose mode where teacup provides a bit more information about its internal activities.

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.

KEYWORDS

TEA, TEAPOT, client, package management, repository