|
Tcl Dev Kit 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.
|
