 |
ActiveTcl User Guide |
 |
[ Main Table Of Contents | Table Of Contents | Keyword Index ]
teapot-md(n) 1.0 tpm "TEA Package Management"
teapot-md - TEApot Meta Data Specification
TABLE OF
CONTENTS
DESCRIPTION
Fundamental
format
Embedded
Format
Meta data
storage
Zip Archives
Tcl Modules
Starkits and Starpacks
Profiles
Keywords with predefined
semantics
Entity
references
Backward compatibility
Example entity references
BUGS,
IDEAS, FEEDBACK
SEE ALSO
KEYWORDS
COPYRIGHT
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.
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.
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.
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
|
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]}
|
In Tcl Modules the meta data is stored using the embedded format documented above.
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 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 is detected by the presence of the marker keyword Profile. The value of this keyword is irrelevant
and ignored, only its (non-)presence counts.
Examples of profiles would be all of Tcllib, or the whole of
ActiveTcl.
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.
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
- -archglob globpattern
- If specified multiple times only the last value is
relevant.
The value is a glob-pattern. The Platform
information of a candidate package has to match this pattern to be
valid and used.
- -exact bool
- Backward compatibility option. The value is a boolean flag
indicating if the exact version of the package is requested or not.
True requests an exact version. For the
details see the section Backward
compatibility.
- -is entity
- If specified multiple times only the last value is relevant. If
not specified at all the value defaults to package.
The value is either package or application, specifying the type of the referenced
entity.
- -platform name
- If specified multiple times only the last value is
relevant.
The value has to be one of unix, windows, or macosx. The reference
is valid if and only if the variable tcl_platform(platform) on the client performing the
reference resolution contains the same value.
In other words, this option is a guard, and makes the reference
conditional on the platform of the client. I.e. the referenced
packages is needed if and only if the platform is correct.
An actual use case is Tcllib's autoproxy
package. It requires the package registry
for its operation, but this is valid only for windows. This is
specified in the meta data of autoproxy as
| |
Meta Require {registry -platform windows}
|
A windows client will follow the reference. All other clients
will ignore it.
- -require req
- If specified multiple times the acceptable set of versions is
the union of the specified ranges.
The value specifies the range of versions which are acceptable. It
is a list of one or two elements, specifying the min and max
versions for the range. The maximum is exclusive, i.e. it is the
first version which is not acceptable anymore. Note that the
recognized forms are the same forms which are accepted by the
builtin command package require
- X.y
- This is equivalent to {-require X.y-(X+1)}. All versions since
X.y are acceptable, until the next major version, i.e. X+1.
- MIN-MAX
- The acceptable range begins at version MIN and ends at version
MAX, exclusive.
- MIN-
- The acceptable range starts at version MIN and there is no
maximum. It can also be said that the maximum is infinity.
- {MIN MAX}
- Deprecated. See "MIN-MAX".
- {MIN {}}
- Deprecated. See "MIN-".
- -version v
- Backward compatibility option. The value is a version number,
the version of the package which has been requested. For the
details see the section 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 {}}
- 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.
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.
teacup, teapot, teapot-admin, teapot-pkg
TEA, TEAPOT, archive, development, generation, meta data, package management, packager, syntax
Copyright © 2007 ActiveState Software Inc.
|
