teapot-md(n) 1.0 tpm "TEA Package Management"
Name
teapot-md - TEApot Meta Data Specification
Description
This document specifies the basic syntax of teapot meta data, the embedding of meta data into various types of files, and the set of standard keywords used by ActiveState, including their meaning.
Fundamental format
The basic format of TEApot meta data is that of a Tcl script in the form
ENTITY name version Meta keyword1 word ... Meta keyword2 word ... Meta keyword3 word ... ...
The format allows the description of more than one entity within the stored meta data, by simply storing several of the text blocks shown above in the same file. This is required if and only if a single file is used to hold the meta data of several entities sharing a single directory.
In the above pseudo-example, ENTITY is a placeholder for the actual command starting the description of an entity, which is either Package, Profile, or Application, for the description of packages, profiles, and applications respectively. It starts the block of meta data describing the named and versioned entity. The block ends at either the next entity command, or the end of the file, whichever comes first.
Note that the entity version number has to use the same syntax as specified in TIP 268. This matches the requirements of Entity references and Tcl itself.
The actual meta data for the entity is defined by the sequence of Meta commands and their arguments. The value associated with the keyword is the list of words coming after it. Any keyword may also occur multiple times in Meta commands. In that case its value is the concatenation of all lists associated with the individual occurrences. If, for example, the meta data is stored as
Meta KEY word1 word2 ... Meta KEY word1' word2' ...' ...''
then the actual value for KEY is
[list word1 word2 ... word1' word2' ...' ...'']
As a second example, the values resulting from the definitions
Meta Require {Tcl 8.2} {md5 2} struct::list
and
Meta Require {Tcl 8.2} Meta Require {md5 2} Meta Require struct::list
are identical.
Another important issue is the case-sensitivity of keywords. They are not. Case-sensitive keywords imply that, for example, Description and description can have different meanings and usage. No use-case could be thought of where such a distinction makes sense. Therefore the system will not make any distinctions based on letter-case.
On the other hand, the values associated with the keywords are case-sensitive.
The format described above is also called the external meta data format.
Embedded Format
The second format is for the embedding of meta data into tcl scripts. In this format, all the commands of the fundamental format are put into Tcl comments, with one command per line, and the whole block is bracketed by the markers # @@ Meta Begin and # @@ Meta End. Our example is for a simple Tcllib package:
# @@ Meta Begin # Package comm 4.4.1 # Meta category Remote communication # Meta description A remote communication facility for Tcl (7.6, 8.0, # Meta description and later) # Meta platform tcl # Meta require {Tcl 8} # @@ Meta End
Meta data storage
Zip Archives
For zip archives containing a teapot package the meta data is stored in the file "teapot.txt" in the archive, using the fundamental format as documented above. For compatibility with older incarnations of the teapot system a copy of the meta data is also stored in the per-archive comment of the zip archive.
Our example is for Iwidgets:
Package Iwidgets 4.0.2 Meta category Widget set Meta description This set of mega-widgets delivers many new, general Meta description purpose widgets like option menus, combo boxes, Meta description selection boxes, and various dialogs whose Meta description counterparts are found in Motif and Windows. Meta platform tcl Meta require {Itcl 3.2} Meta require {Itk 3.2} Meta require {Tcl 8.0} Meta require {Tk 8.0} Meta subject iwidgets widget toolkit Tk megawidget {[incr Tcl]} Meta subject {[incr Tk]} Meta summary A megawidget set based on {[incr Tcl]} and {[incr Tk]}
Tcl Modules
In Tcl Modules the meta data is stored using the embedded format documented above.
Starkits and Starpacks
Starkits are in essence Tcl Modules with a Metakit filesystem attached at the rear. The meta data is searched first in the header, as if it were a regular Tcl Module. Only if nothing was found in the header is the attached filesystem inspected as well. In that case a file "teapot.txt" is sought in the top directory of the filesystem, and it has to contain the meta data using the external format.
For a starpack the same procedure is followed, except that finding the meta data in the binary header is highly unlikely. It is possible however, if the C code of the runtime embedded the information in a string constant.
Profiles
Profiles are packages whose functionality is irrelevant and ignored. Only their meta data is used. As such their minimal representation is as a Tcl Module without actual code and containing only the meta data, using the embedded format. They are used by the TEApot system to define named collections of packages and applications.
A profile has the entity type Profile. Older profiles have the entity type Package and a marker keyword Profile whose actual value is irrelevant. This old form is still supported by the various tools for reading, for backward compatibility. This form is not generated anymore however.
Examples of profiles would be all of Tcllib, or the whole of ActiveTcl.
The client tool teacup is also able to print the results of list and search queries in the form of a profile, allowing the easy generation of more examples as well.
Keywords with predefined semantics
The semantics of the keywords listed below are defined by the TEAPOT system and the provided applications. In other words, the TEAPOT applications rely on them being used by packagers as specified.
- Autopath
-
This information is optional. It represents an advanced feature of the package generator, teapot-pkg. Its manpage explains more.
- Category
-
The value is interpreted as a string describing the Subject of the entity in a one-line sentence instead of a list of key-phrases. As such it is similar to Summary. The string is created by joining the words of the list.
- Description
-
The value is interpreted as a string describing the entity in free-form. The string is created by joining the words of the list. This is the information returned by teacup describe.
- Entity
-
Reserved. This keyword is used by repositories to reflect the type of the entity the meta data is for into the meta data itself. Anything a user may have stored under this will be lost. This enables repository users to search by entity via the general search facility.
- EntrySource
-
Their value is a list of paths containing the files in the package, relative to the package directory, which are sourced to activate the functionality of the package. This is information for the package generator, teapot-pkg. Its manpage explains more.
- EntryLoad
-
Their value is a list of paths containing the files in the package, relative to the package directory, which are loaded to activate the functionality of the package. This is information for the package generator, teapot-pkg. Its manpage explains more.
- EntryKeep
-
The value of this keyword is irrelevant and ignored. The presence of this keyword instructs the package generator, teapot-pkg, to keep an existing package index file ("pkgIndex.tcl") instead of generating one. Its manpage explains more.
- EntryTclCommand
-
The value of this keyword is the actual load command of the package. The presence of this keyword instructs the package generator, teapot-pkg. to not generate a load command of its own. Its manpage explains more.
- Excluded
-
This information is optional. When present it is a list of glob patterns specifying which files to not include in the package. This is information for the package generator, teapot-pkg. Its manpage explains more.
- Included
-
The information is optional. When present it is a list of glob patterns which specify which files should be included into the list of files for the package. This is information for the package generator, teapot-pkg. Its manpage explains more.
- InitPrefix
-
This information is optional. It represents an advanced feature of the package generator, teapot-pkg. Its manpage explains more.
- Name
-
Reserved. This keyword is used by repositories to reflect the name of the entity the meta data is for into the meta data itself. Anything a user may have stored under this will be lost. This enables repository users to search by name via the general search facility.
- Platform
-
The value is interpreted as a string naming the architecture the entity is for. This is a value as generated by the command platform::identify provided by the package platform. Using the value tcl indicates that the entity is written in pure Tcl, without any binary parts.
This keyword has to be present in the meta data to fully identify the entity. It cannot be left out.
- Profile
-
Deprecated. In older releases of teapot a profile was a package with this keyword present in its meta. This form is still recognized, however the recommended form is to identify profiles through the use of Profile as their entity type.
The actual value of this keyword is irrelevant. Only the (non-)presence of the keyword has meaning. If the keyword is present the entity (should be a package) is a Profile, i.e. a package without actual code, and only requirements. Such packages are not installed, and only used in dependency-resolution.
- Recommend
-
The value is interpreted as a list of entity references, with each word one reference. The referencing entity is operational without them, however it may be better, faster, etc. when they are present.
The format of these references is specified in section Entity references
- Require
-
The value is interpreted as a list of entity references, with each word one reference. The referenced entities are required for the referencing entity to be operational.
The format of these references is specified in section Entity references
- Subject
-
The value is a list of key-phrases for use in an index.
- Summary
-
The value is interpreted as a free form string containing a brief, one-line description of the package, suitable for brief listings and tables of contents. The string is created by joining the words of the list.
- tcl_findLibrary/force
-
This information is optional. It represents an advanced feature of the package generator, teapot-pkg. Its manpage explains more.
- Version
-
Reserved. This keyword is used by repositories to reflect the version of the entity the meta data is for into the meta data itself. Anything a user may have stored under this will be lost.This enables repository users to search by version via the general search facility.
Entity references
An entity reference is a list of the general form
name ?requirement?... ?-option value?...
with the name, requirements and all options and values each one word of the list. The smallest possible form is a list containing just the name as its first and only element.
Each requirement between name and options is a short form for "-require requirement", and the value has the same syntax as the value for the option. Using this form allows the specification of requirements using the same syntax as specified in TIP 268. Especially when no further options are required.
The recognized options are
Backward compatibility
. For backward compatibility a reference may contain the options -version and -exact to simulate the older forms of package require statements. They are translated internally to
- -version X.y -exact 1
-
=> -require {X.y X.(y+1)} This means that exactness is only to the level of granularity specified, and below that we are free to choose unexact.
- -version X.y -exact 0
-
=> -require {X.y {}}
- -version X.y
-
=> -require {X.y {}}
Example entity references
- FOO
-
This refers to package FOO (The entity-type defaults to package). Any version is acceptable.
- FOO -is application
-
This refers to application FOO. Any version is acceptable.
- FOO -version 2.1
- FOO -require 2.1
- FOO 2.1
-
Package FOO is asked for, at least version 2.1 or higher, but not as high as version 3.
- FOO -version 2.1.1 -exact true
- FOO -require 2.1.1-2.1.1
- FOO 2.1.1-2.1.1
-
Version 2.1.1 of package FOO is asked for. Note that version 2.1.1.2, 2.1.1.6, etc. are all valid. The exactness is only to the level specified. Below that the versions are allowed to vary.
- FOO -require 4.3-4.5
- FOO 4.3-4.5
-
Acceptable versions of package FOO are 4.3 and higher, and have to be below version 4.5.
- FOO -require 4.8-
- FOO 4.8-
-
Versions 4.8 and higher of package FOO are acceptable, with no upper limit.
- FOO -require 4.3-4.5 -require 4.7
- FOO 4.3-4.5 4.7
-
Versions 4.3 and higher, and below 4.5 are acceptable, as are version 4.7 and higher, and below version 5. This accepts everything between versions 4.3 and 5, except for all versions between 4.5 and 4.7 (exclusive).
- FOO -archglob *-sparc
-
This references all versions of package FOO which are for a sparc based system, independent of operating system.
BUGS, IDEAS, FEEDBACK
This document 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.
Keywords
TEA, TEAPOT, archive, development, generation, meta data, package management, packager, syntax
Copyright
Copyright © 2007-2008 ActiveState Software Inc.