Product Documentation

TDK 4.1 Documentation

Table of Contents

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

teapot-pkg(n) 1.0 tpm "TEA Package Management"

NAME

teapot-pkg - TEApot Package Tool

TABLE OF CONTENTS

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    Commands
    Archive Type Selection
    Meta Data Requirements
    BUGS, IDEAS, FEEDBACK
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

teapot-pkg generate ?--timestamp|-T? ?--output|-o output? ?--type|-t format? ?--compile|-c? packagedir
teapot-pkg ignore add pattern...
teapot-pkg ignore remove pattern...
teapot-pkg ignore list
teapot-pkg version
teapot-pkg who
teapot-pkg show ?--human|-h|--external|-x|--embedded|-e? file
teapot-pkg help
teapot-pkg edit file change...
teapot-pkg scan dir...

DESCRIPTION

This document assumes that the reader has read at least the TEApot Introduction, the TEApot Glossary of Terms, and possibly the TEApot Meta Data Specification.

This tool provides the ability to generate, inspect, and edit entity archive files from the command line. Tcl Dev Kit's Package Editor Tool is the visual complement.

The first of these functions, archive generation, relies on the presence of a file "teapot.txt" in the directory of the package(s) and containing its/their meta data (fundamental format). To help with the transition of existing packages to the use of TEApot meta data the tool also provides a scanner which extracts basic information from such packages using a set of heuristics and stores them as proper TEApot meta data.

Commands

teapot-pkg generate ?--timestamp|-T? ?--output|-o output? ?--type|-t format? ?--compile|-c? packagedir
Reads the meta data stored in the file "teapot.txt" found in the directory packagedir (or sub-directories) and uses the information to generate one or more package archives of the given type. The allowed type values are listed below. Note that the application uses case-insensitive string comparisons when checking the legality of the format argument.

Available formats (--type values)



auto
This, the default format, is special. It tells the generator to choose the archive type (zip or tm, see below) on its own on a per-package basis, using the meta data of the package and the files found in it to make that decision. The used rules are explained in the section Archive Type Selection.

tm
Generate Tcl Modules. Fails for packages which do not fit.

zip
Generate Zip archives.

pkgIndex
This backend is special as well, it does not generate archives, but files "pkgIndex.tcl".

If output is not specified then the files are put into the directories where the packages were found. Otherwise a single master "pkgIndex.tcl" is generated in the output directory, listing all the found packages in one file.



If output is specified and exists it has to be a directory. This is required as the generator may create multiple archives during its recursion through package and its sub-directories. If the path does not exist it will be created. If output is not specified the application defaults to the current working directory.

If option --compile is specified all Tcl files for the package are bytecode-compiled before being put into the package archive file. A Tcl file is any file with the extension ".tcl", except for "pkgIndex.tcl". When this option is used the requirements of the package are automatically updated to require the package tbcload.

The names of the created archives are constructed from entity, type, name, version, architecture, and chosen archive file format.

Note that the application will recurse the whole directory hierarchy starting at package in search of possible packages. The recursion stops in any directory containing one or more packages. I.e. packages cannot be nested inside of other packages.

The only exception to this are profile packages (short: profile). For a directory containing the basic definition of a single profile its subdirectories are searched and the found packages are recorded as requirements of the profile.

Any other combination of profiles and regular packages, like a directory containing multiple profiles, or a mixture of regular packages and profiles is an error. Such errors are reported, but do not stop the application from scanning for more packages.

If, and only if the option --timestamp is specified, a timestamp in the format "YYYY.MM.DD.hh.mm.ss" will be appended to the package versions recorded in the generated archives. Note however that leading zeros in a version segment are not allowed and stripped out.

teapot-pkg ignore add pattern...
This command adds the specified glob patterns to the list of directories to ignore during package generation. This information is saved in the teapot configuration.

teapot-pkg ignore remove pattern...
This command removes the specified glob patterns from the list of directories to ignore during package generation. This information is saved in the teapot configuration.

teapot-pkg ignore list
This command lists what standard glob patterns are used to detect which directories to ignore during package generation. This information is read out of the teapot configuration.

teapot-pkg version
Prints the version number of the application.

teapot-pkg who
Prints the complete teapot meta data of the application.

teapot-pkg show ?--human|-h|--external|-x|--embedded|-e? file
Extracts the meta data from the specified archive file and prints it to stdout in one of three formats. The default, if no format is specified, is --human. This formats the meta data for human consumption. The other two formats, --external and --embedded, generate output for placement of the meta data into a "teapot.txt" file or a TclModule, respectively.

teapot-pkg help
Prints basic usage information to stdout.

teapot-pkg edit file change...
This method edits the meta data in the specified archive file per the given changes. Files in the archive file cannot be edited. Each change is specified by a command argument followed by a fixed set of arguments, their number depending on the command. The accepted commands are:



c pattern
clear pattern
The two forms above all remove all keys matching the glob pattern from the meta data.

= key value
set key value
The two forms above all add the value to the meta data key, treating an existing value for the key as a list to extend. If key does not exist it is created.

! key
- key
unset key
The three forms above all remove the named key from the meta data.

name: value
Rename the entity, value is the new name.

version: value
Change the version number of the entity, value is the new version.

type: value
Change the type of the entity, value is the new entity type.



teapot-pkg scan dir...
This method iterates over the specified directories, ignoring all not containing a "pkgIndex.tcl" file. For the others the files in the directory are scanned and teapot meta data is generated through a set of heuristics. The results are written to "teapot.txt" files, one per directory scanned.

The heuristics inspect the "pkgIndex.tcl" file to determine the packages provided by the directory, i.e. their names and versions. Their load commands are inspected to determine which files are the entry point(s) to their implementation.

These entry points are further inspected for package require and source commands, providing information about package dependencies, and other files belonging to a package. Note that caught package requirements are considered to be recommendations, everything else are requirements.

The generator inspects all files matching the pattern "*.man" and checks if they are documentation written in the doctools markup language. If yes information about the package name, version, description, etc. is extracted. If the information in a file is sufficient to associate it with a package the extracted information is put into the meta data for that package.

The generator looks for and recognizes the following pragmas/hints in the comments of Tcl files, and uses them to extend its knowledge of which files belong to what packages:



  1. Each pragma is in a Tcl comment, on a single line.

  2. A pragma is introduced by either @mdgen or @md_pragma. This has to be the first word in the comment, with only whitespace between it and the comment character.

  3. After the introductory marker, separated by whitespace, three commands are recognized. Each command takes one argument, separated from the command by a sequence of whitespace, ":", and whitespace again. The argument goes until the end of the line, except for trailing whitespace.

    OWNER
    The argument is a path relative to the package directory. The named file belongs to the same package as the file containing the pragma.

    EXCLUDE
    The argument is a path relative to the package directory. The named file does not belong to any package.

    NODEP
    The argument is a package name. The named package is neither requirement nor recommendation for the package the file belongs, whatever the commands in this file say otherwise. It may however be named as a requirement/recommendation by other files belonging to the same package.



Examples:
 
  # @md_pragma NODEP: pluginmgr
  # @md_pragma NODEP : perfiffle
  # @mdgen EXCLUDE: scripts/example.tcl

Archive Type Selection

If the format auto was specified the package generator is free to choose the format of the package archive file on its own. This is done according to the rules listed below. The rules are considered in order and the format specified by the first matching rule is used.

  1. For profile packages the format is tm.

  2. For a package which is not pure Tcl the format is zip.

    Note that a package with an architecture not equal to "tcl", but not containing any file matching "*.so", "*.sl", "*.dll", or "*.dylib" is considered to be a pure Tcl package.

  3. For a package without files (bundle, or alias, via package index) the format is tm.

  4. For a package containing one or more files, all of which are listed as entry points, the format is tm.

  5. For all other packages the format is zip.

Meta Data Requirements

The package generator recognizes and uses a number of keywords in the meta data for its own operation. These are listed below. With the exceptions of Platform and Require none of the keywords listed below are passed through to the meta data stored in the archives. They are relevant to the developer and package generator, but not the person installing and/or using the package.

Regarding the keywords Entry*, one of them has to be present, and each excludes all the others.

Autopath
This information is optional. It represents an advanced feature of the package generator influencing the generation of package index files. The value of the keyword is irrelevant and ignored. If present the backend will generate a package load command which extends the autopath of the Tcl interpreter with the path to the package before executing its entrypoints.

Circles
This information is optional. It represents an advanced feature of the package generator influencing the generation of package ifneeded scripts and package startup code. The value of the keyword is a list of names, a subset of the required packages. It names the packages which are circular dependencies of the package. If present the backend will generate a special code to handle the circularity during package load.

EntryKeep
The value of this keyword is irrelevant and ignored. The presence of this keyword instructs the generator to keep the existing "pkgIndex.tcl" file of the package instead of generating one. Note that the backends for generating Tcl Modules and Package indices are unable to handle this instruction and will throw errors. Only the Zip and Auto backends are able to handle it.

This feature is present to ease the transitioning of packages with complex package indices to TEApot.

EntryLoad
EntrySource
Its value is a list of paths denoting the files in the package, relative to the package directory, which are either loaded or sourced to activate the functionality of the package. This information is used when generating either the header of a Tcl Module, or the file "pkgIndex.tcl".

EntryTclCommand
The value of this keyword is the actual load command of the package. The presence of this keyword instructs the generator to not generate a load command of its own, but to use this one. The advanced features triggered by the keys Autopath and tcl_findLibrary/force (see below) are still taken into account, i.e. code is generated for them, but not for the advanced feature normally triggered by InitPrefix.

Excluded
This information is optional. When present it is a list of glob patterns specifying which files to not include in the package. When not present the list of files to exclude from the package is empty.

The final list of files for a package is the list of included files minus the list of excluded files.

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. The information is always initialized with the name of the entry file as it was specified by either EntrySource or EntryLoad.

InitPrefix
This information is optional. It represents an advanced feature of the package generator influencing the generation of package index files. The value of the keyword is interpreted as a dictionary mapping from files in the package to strings. If present the backend will generate a series of Tcl commands which will load/source each of the listed files and the associated strings put after these commands with only a space as separation. I.e it will interleave the load/source statements and the associated strings. This makes the meaning of the strings depending on how the file is used by the package.

  1. For files loaded into the interpreter the associated string becomes the name of the package to use when creating the name of the Init function to call. I.e., assuming that BAR is the string which is associated with the loaded file "FOO.so" instead of a plain
     
        load FOO.so

    the system generates

     
        load FOO.so BAR



  2. For sourced files however the string will make sense if and only if starting with a semicolon, or newline, i.e. making it a separate command, maybe even script, which runs after the file has been sourced. Without that additional separation an associated string will simply cause a syntax error at runtime. Assuming that the sourced "FOO.tcl" is associated with "; # Helper functions" the generated code will contain

     
        source FOO.tcl ; # Helper functions

Platform
Required keyword. See the predefined semantics. This is used as part of the archive name, for the cases when a name is generated and not taken from the user. The information is passed through into the generated archives as well.

Require
Optional keyword. See the predefined semantics. When present its value is searched for dependencies on the Tcl core, to determine the lowest version of Tcl the package will run with. This is used by the Zip archive backend when generating the file "pkgIndex.tcl" to properly guard the package ifneeded statement. The information is passed through into the generated archives as well.

tcl_findLibrary/force
This information is optional. It represents an advanced feature of the package generator influencing the generation of package index files. The value of the keyword is interpreted as the base name XXX for an environment variable. If present the backend will generate a package load command which sets the environment variable XXX_LIBRARY to the path to the package before jumping to its entry.

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 teapot-pkg application with the problem in question can be queried with the command version

SEE ALSO

teacup, teapot, teapot-admin, teapot-md

KEYWORDS

TEA, TEAPOT, archive, development, generation, package management, packager

COPYRIGHT

Copyright © 2006-2007 ActiveState Software Inc.