TIP:            78
Title:          TEA 2.0 Definitions
Version:        $Revision: 1.3 $
Author:         Andreas Kupries <andreas_kupries@users.sourceforge.net>
Author:         Larry W. Virden <lvirden@yahoo.com>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        15-Dec-2001
Post-History:   

~ Abstract

This document is an informational TIP providing definitions for
commonly used terms (like package, extension, core, distribution,
etc.) to make future communication among people in the community
easier.  It is recommended that future and past documents specifying
details inside of the greater context of TEA refer to this document to
ensure a consistent usage of terms.

~ Background

This document is an adjunct to the [[TIP <<vision>>]].  ''(DKF - Is
this meant to be a reference to [34]?  Edit to such if so...)''

To facilitate the specification and adoption of clearly defined
interfaces to various activities and technologies it specifies a
number of terms used by the community at large to create a greater
unity and coherence in the usage of these terms.  In other words, by
creating generally accepted definitions for important terms the risk
of misunderstanding each other is reduced.

~ Specification of Technical Terms

This section specifies a number of important technical terms in
alphabetical order.  Terms used inside of a specification are
highlighted.

 * Application

 > An entity implementing some functionality required by a ''P/A
   User'' (see section ''Roles'') to perform his work.  Consists of
   one more files.  May make use of ''packages'' to implement its
   functionality.

 * Archive

 > Encapsulation of a ''distribution'' in a single file.  Well-known
   formats for archives are tar, gzipped tar, bzipped tar, and zip.

 * Binary generation

 > The process of wrapping up a built package into a binary
   ''distribution''.  See ''building'' too.

 * Building

 > The process of ''configuring'' and ''transforming'' a source
   ''distribution'' into a set of files which can be either
   immediately installed on the site which built them or wrapped into
   a binary ''distribution'' for shipment to other sites.  This also
   includes the execution of a test-suite coming with the package.

 * Bundle

 > A ''distribution'' encapsulating more than one ''package''.

 * Catalog

 > A catalog is a site providing an index of the packages.

 * Configuration

 > The process of customizing a source distribution for a particular
   architecture and/or site.  A part of ''Building''.

 * Conflict

 > Two or more packages are said to be in conflict if the usage of one of them
   excludes the usage of the others.

 > In a ''strong conflict'' installing one of the packages disallows
   even the installation of the others.

 * Core

 > A shorthand for ''Tcl core''.

 * Core distribution.

 > See ''Tcl core distribution''.

 * Dependency

 > A relationship between packages.  A package X is said dependent on
   another package Y if said package Y is required to allow X to work.

 > There are several types of dependencies:

 > * Build-time dependency

 > > Y is required to allow X to be build.

 > * Run-time dependency

 > > Y is required to allow the usage of an installed X.

 > * Optional dependency

 > > Y can be used by X (usually for improved performance) but is not
     required for building or use.

 * Distribution

 > An encapsulation of one or more ''packages'' for transport between
   places, machines, organizations, and people.  Several types of
   distributions are possible, explained below.

 > 1. binary

 > > A binary distribution is in a state and format allowing the
     installation of the contained packages on a particular platform.

 > > It contains at least all the files

 > > * implementing the functionality of the distributed packages and

 > > * required to allow the package management of the Tcl core to
       handle the packages.

 > > A binary distribution usually contains just the files for a
     single architecture.  This is not a explicit requirement however.
     In other words, a binary distribution is allowed to contain the
     files for several architectures.  Such a binary distribution will
     be called a ''fat binary distribution''.

 > > We distinguish between three sub-types:

 > > * installable

 > > > This is the minimal binary distribution we spoke of before.

 > > * auto-installable

 > > > Like ''installable''', but additionally contains an application
       whose execution will perform all the steps which are necessary
       to install the contained packages at a site.  The installation
       to add the packages to (and thus the location of the installed
       packages) can be freely chosen by the caller of the executable.

 > > * auto-image

 > > > Like ''auto-installable'', but the final location of the
       packages is hard-wired into the distribution.  This means that
       a site using auto-images is restricted to one installation per
       architecture for which files are contained in the binary
       distribution.

 > > > Some of the existing archive formats restrict their contained
       distributions to this type.  Examples of such archive formats
       are

 > > > * RPM (RedHat Package Manager)

 > > > * DEB (DEBian Linux package format)

 > > See [TIP 55] for the specification of a proposed layout for
     binary distributions.

 > 1. bundle

 > > A distribution which either contains the distributions of more
     than one package or a list of references to packages.  The
     references are done by specifying the name and version of the
     packages contained in the bundle.

 > 1. buildable

 > > See ''source''.

 > 1. compileable

 > > See ''source''.

 > 1. raw

 > > A raw distribution is the most fundamental distribution.  Its
     format is nearly completely unspecified.  Its contents are
     straight from a source repository.  The process of converting a
     raw distribution into a source distribution is called
     ''Preparation''.

 > > Because of the unformatted nature of a raw distribution the
     commands for its conversion into a source distribution have to be
     part of it.  This is the only part of a raw distribution which
     can and has to be specified.

 > > Example: The execution of ''autoconf'' to generate a
     ''configure'' script from its ''configure.in'' file can be a
     single step in a complex preparation.

 > 1. source

 > > A source distribution is in a format and state where tools can be
     used to build its contents.

 > > The format needs further specification but for now we can assume
     that it is governed by the current TEA specification.

 > > Alternate name for this type of distribution are ''compileable''
     and ''buildable''.

 * Distribution repository

 > See ''repository''

 * Extension

 > Alternate name for a ''package'', generally used for packages
   requiring compilation to become functional.

 > This term is ''deprecated''.

 * Installation

 > A special type of ''distribution repository, binary'' (see
   ''repository'') containing all ''packages'' which were installed on
   a site.  A site may host several installations differing in version
   and/or configuration of Tcl, and/or the platform Tcl was built for,
   etc.

 > Currently difficult to do but in the future it should made be
   possible for an installation to refer and use another installation,
   provided both are configured identically.  This allows a site to
   build a hierarchy of installations from the most general containing
   the common packages down to installations associated with one or
   more ''P/A Developers''.

 * Installing

 > The process of unpacking a binary distribution and adding the
   contained packages to an ''installation''.  The latter may include
   moving files to their proper places.

 > Also the process of adding a built package to an ''installation''.

 * Manifest

 > A file detailing the files making up a particular package.

 * Package

 > A collection of files providing additional functionality to a user
   of a Tcl interpreter when loaded into said interpreter.

 > Some files in a package implement the provided functionality
   whereas other files contain meta-information required by the
   package management of Tcl to be able to use the package.

 * Preparation

 > The process of converting a raw ''distribution'' into a source
   ''distribution'' suitable as input to ''building''.  This includes
   actions like:

 > * Retrieval of sources from a source repository

 > * Creating a ''configure'' file from its ''configure.in''.

 > * Creating the distributed documentation from internal sources.

 > * Removal of internal files containing notes, scratch info and the like.

 > * Inserting version information into files.

 > * ...

 > The tool ''makedist'' (which I wrote) is in my mind when thinking
   about this step.

 * Raw retrieval

 > The process of retrieving a raw ''distribution'' from a ''source
   repository''.

 * Repository

 > General term with two possible meanings.

 > 1. A collection of ''archives''.  The exact term for this type of
     repository is "distribution repository".

 > > If a distribution repository is restricted to one type of
     distributions this type can be added to the term as further
     specification of the type of repository.  Thus

 > > * ''distribution repository, binary'', or

 > > * ''distribution repository, source''.

 > 2. A collection of directories, developer files and control files
      containing version control information.  The exact term for this
      type of repository is ''source repository''.

 > > A repository can either be internal to an organization or public.

 * Source repository

 > See ''repository''

 * Tcl core

 > The most fundamental part in the Tcl world; the interpreter engine
   and the builtin commands coming with it.  These are all commands
   and procedures reported by ''info commands'' for a ''tclsh'' which
   was started with an empty ''.tclshrc'' file and after sourcing all
   ''.tcl'' files in the directory returned by ''info library''.

 * Tcl core distribution

 > The most fundamental distribution there is.  Contains the ''Tcl
   core'' and a number of packages.

~ Roles

The terms in the preceding section specified both passive data
structures and actions upon them.  This section specifies the possible
actors, i.e. entities which perform one or more of these actions.

To make the specification easier, related actions are grouped into
roles of behavior.  The mapping from roles to actual actors,
i.e. people and organizations is n:m.  On other words, one actor may
have several roles, either at once or changing over time and one role
can be held by several distinct actors.

Examples are given at the end of this section.

 1. Catalog manager

 > A catalog manager handles one or more catalogs.  He is responsible
   for

 > * the final name arbitration for packages with conflicting names

 > * and the categorization of the packages indexed by the catalog.

 1. P/A Builder

 > A package and/or application builder is a person and/or organization

 > * who retrieves raw distributions from source repositories and (in
     a sequence of several steps) generates binary distributions from
     them.

 > * or who retrieves source distributions from distribution
     repositories and (in a sequence of several steps) generates
     binary distributions from them.

 > * uploads the generated binary distributions into one or more
     distribution repositories.

 > * uploads the generated source distributions into one or more
     distribution repositories.

 > The intermediate steps performed by a builder are ''Preparation'',
   ''Building'', and ''Binary generation''.

 > If ''System administrator'' and ''P/A Builder'' coordinate with each other
   it is also possible to install a package directly from the built
   package.

 > ''NOTE:'' Think about splitting P/A Builder into two roles; one for
   the preparation of source ''distributions'' and a second role for
   the generation of binary ''distributions''.

|         TODO Find some nice names for the split roles.

 1. P/A Developer

 > A developer is a ''P/A User'' whose tasks include the creation of
   new packages and/or applications.  A workspace contains the raw
   sources of these new packages and applications.  For posterity and
   version control it is kept synchronized with one or more ''source
   repositories''.

 > During development, at least one installation has to be accessible,
   containing the initial packages, the new packages and the
   applications built upon the packages.

 1. P/A User

 > A person or organization which uses Tcl based tools but does not
   develop new code.  Its workspace contains the files required for
   the tasks at hand.

 > The border between the roles of P/A Developer and P/A User blurs if
   the tool being used allows one to customize/program/extend it in
   Tcl.

 1. Repository manager

 > This role handles the management of all types of ''repositories''.
   This role is not part of the development process ''per se'' and has
   no direct actions for with regards to distributions, packages,
   sources, etc.

 > Repository managers are responsible for keeping the system up and
   running, doing adequate backups, supporting mirrors, providing
   browsing and download capabilities, providing confidence that
   updates to items in the repository are being done by the approved
   person or persons, etc.

 > The role is related to ''System administrator'', but not the same.
   It was split out of that role because a ''System-Administrator'' is
   usually internal to an organization whereas a repository and its
   management can be provided by an entity external to the
   organization.

 1. System administrator

 > A system administrator manages

 > * one or more ''installations'' of the Tcl core and additional
     packages.  Each installation may be configured differently (Tcl
     version, installed packages, platform, ...).

 > * Installed packages are taken either from a ''distribution
     repository'' or directly from a built package.  The latter has to
     be done in coordination with a ''P/A Builder''.

 > Her responsibilities include

 > * the creation of empty installations, 

 > * the destruction of installations,

 > * the addition and removal of packages to/from an existing
     installation.

The three P/A roles are central to the development process and bound
together in a tight loop of information flowing between them.  The
other three roles handle the support structure without which the other
roles would be unable to communicate and collaborate.

#image:78pa_cycle

Examples:

 * Larry Virden is ''System-Administrator'', ''P/A Builder'' and ''P/A
   User'' for his organization.

 * I (the author of this TIP) am all roles, on my system at home.

 * ActiveState is ''Repository Manager'' for the Perl community and
   plans to become one for the Tcl community.

 * SourceForge is a combination of ''Repository Manager'' and
   ''Catalog Manager''.

 * Most people with a windows machine at home are
   ''System-Administration'' and ''P/A User'' for this machine.

~ Visual Representation

The following drawings are a visual adjunct to the terms in the last
sections to aid in the understanding of the terms and their relations.

Legend:

 * Blue rounded boxes - Areas of responsibility for roles.  The
   responsible role is written in gold text inside of the box.

 * White rounded boxes with a black border - Data, like packages,
   distributions, etc.

 * White boxes with a red border - Actions on data.

#image:78tea_terms_relations_1 Roles, Data and Actions

#image:78tea_terms_relations_2 Relationships Between Data Entities

~ Copyright  

This document has been placed in the public domain.http://www.tcl.tk/cgi-bin/tct/tip/78.html
