\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#78: TEA 2.0 Definitions}
\date{December 15, 2001}
\author{Andreas Kupries, Larry W. Virden}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#78}&\textbf{TEA 2.0 Definitions}\\\hline
Author&

Andreas Kupries \tipmail{andreas_kupries}{users.sourceforge.net}
\par
Larry W. Virden \tipmail{lvirden}{yahoo.com}
\\
Created&Saturday, \(\text{15}^{\text{th}}\) December 2001\\
Type&Informative\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

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.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

This document is an adjunct to the [TIP \tiplangle{}\tiplangle{}vision\tiprangle{}\tiprangle{}]. \textit{(DKF --- Is this meant to be a reference to \cite{tip34}? 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.

\section{Specification of Technical Terms}

This section specifies a number of important technical terms in alphabetical order. Terms used inside of a specification are highlighted.
\begin{itemize}
\item{}
Application

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

Encapsulation of a \textit{distribution} in a single file. Well-known formats for archives are tar, gzipped tar, bzipped tar, and zip.
\item{}
Binary generation

The process of wrapping up a built package into a binary \textit{distribution}. See \textit{building} too.
\item{}
Building

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

A \textit{distribution} encapsulating more than one \textit{package}.
\item{}
Catalog

A catalog is a site providing an index of the packages.
\item{}
Configuration

The process of customizing a source distribution for a particular architecture and/or site. A part of \textit{Building}.
\item{}
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 \textit{strong conflict} installing one of the packages disallows even the installation of the others.
\item{}
Core

A shorthand for \textit{Tcl core}.
\item{}
Core distribution.

See \textit{Tcl core distribution}.
\item{}
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:
\begin{itemize}
\item{}
Build-time dependency

Y is required to allow X to be build.
\item{}
Run-time dependency

Y is required to allow the usage of an installed X.
\item{}
Optional dependency

Y can be used by X (usually for improved performance) but is not required for building or use.
\end{itemize}
\item{}
Distribution

An encapsulation of one or more \textit{packages} for transport between places, machines, organizations, and people. Several types of distributions are possible, explained below.
\begin{enumerate}
\item{}
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
\begin{itemize}
\item{}
implementing the functionality of the distributed packages and
\item{}
required to allow the package management of the Tcl core to handle the packages.
\end{itemize}

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 \textit{fat binary distribution}.

We distinguish between three sub-types:
\begin{itemize}
\item{}
installable

This is the minimal binary distribution we spoke of before.
\item{}
auto-installable

Like \textit{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.
\item{}
auto-image

Like \textit{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
\begin{itemize}
\item{}
RPM (RedHat Package Manager)
\item{}
DEB (DEBian Linux package format)
\end{itemize}
\end{itemize}

See [TIP 55] for the specification of a proposed layout for binary distributions.
\item{}
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.
\item{}
buildable

See \textit{source}.
\item{}
compileable

See \textit{source}.
\item{}
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 \textit{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.
\begin{description}
\item[Example]
The execution of \textit{autoconf} to generate a \textit{configure} script from its \textit{configure.in} file can be a single step in a complex preparation.
\end{description}
\item{}
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 \textit{compileable} and \textit{buildable}.
\end{enumerate}
\item{}
Distribution repository

See \textit{repository}
\item{}
Extension

Alternate name for a \textit{package}, generally used for packages requiring compilation to become functional.

This term is \textit{deprecated}.
\item{}
Installation

A special type of \textit{distribution repository, binary} (see \textit{repository}) containing all \textit{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 \textit{P/A Developers}.
\item{}
Installing

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

Also the process of adding a built package to an \textit{installation}.
\item{}
Manifest

A file detailing the files making up a particular package.
\item{}
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.
\item{}
Preparation

The process of converting a raw \textit{distribution} into a source \textit{distribution} suitable as input to \textit{building}. This includes actions like:
\begin{itemize}
\item{}
Retrieval of sources from a source repository
\item{}
Creating a \textit{configure} file from its \textit{configure.in}.
\item{}
Creating the distributed documentation from internal sources.
\item{}
Removal of internal files containing notes, scratch info and the like.
\item{}
Inserting version information into files.
\item{}
...
\end{itemize}

The tool \textit{makedist} (which I wrote) is in my mind when thinking about this step.
\item{}
Raw retrieval

The process of retrieving a raw \textit{distribution} from a \textit{source repository}.
\item{}
Repository

General term with two possible meanings.
\begin{enumerate}
\item{}
A collection of \textit{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
\begin{itemize}
\item{}
\textit{distribution repository, binary}, or
\item{}
\textit{distribution repository, source}.
\end{itemize}
\setcounter{enumi}{1}
\item{}
A collection of directories, developer files and control files containing version control information. The exact term for this type of repository is \textit{source repository}.

A repository can either be internal to an organization or public.
\end{enumerate}
\item{}
Source repository

See \textit{repository}
\item{}
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 \textit{info commands} for a \textit{tclsh} which was started with an empty \textit{.tclshrc} file and after sourcing all \textit{.tcl} files in the directory returned by \textit{info library}.
\item{}
Tcl core distribution

The most fundamental distribution there is. Contains the \textit{Tcl core} and a number of packages.
\end{itemize}

\section{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.
\begin{enumerate}
\item{}
Catalog manager

A catalog manager handles one or more catalogs. He is responsible for
\begin{itemize}
\item{}
the final name arbitration for packages with conflicting names
\item{}
and the categorization of the packages indexed by the catalog.
\end{itemize}
\item{}
P/A Builder

A package and/or application builder is a person and/or organization
\begin{itemize}
\item{}
who retrieves raw distributions from source repositories and (in a sequence of several steps) generates binary distributions from them.
\item{}
or who retrieves source distributions from distribution repositories and (in a sequence of several steps) generates binary distributions from them.
\item{}
uploads the generated binary distributions into one or more distribution repositories.
\item{}
uploads the generated source distributions into one or more distribution repositories.
\end{itemize}

The intermediate steps performed by a builder are \textit{Preparation}, \textit{Building}, and \textit{Binary generation}.

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

\textit{NOTE:} Think about splitting P/A Builder into two roles; one for the preparation of source \textit{distributions} and a second role for the generation of binary \textit{distributions}.
\begingroup\small\begin{verbatim}
         TODO Find some nice names for the split roles.
\end{verbatim}
\endgroup
\item{}
P/A Developer

A developer is a \textit{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 \textit{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.
\item{}
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.
\item{}
Repository manager

This role handles the management of all types of \textit{repositories}. This role is not part of the development process \textit{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 \textit{System administrator}, but not the same. It was split out of that role because a \textit{System-Administrator} is usually internal to an organization whereas a repository and its management can be provided by an entity external to the organization.
\item{}
System administrator

A system administrator manages
\begin{itemize}
\item{}
one or more \textit{installations} of the Tcl core and additional packages. Each installation may be configured differently (Tcl version, installed packages, platform, ...).
\item{}
Installed packages are taken either from a \textit{distribution repository} or directly from a built package. The latter has to be done in coordination with a \textit{P/A Builder}.
\end{itemize}

Her responsibilities include
\begin{itemize}
\item{}
the creation of empty installations, 
\item{}
the destruction of installations,
\item{}
the addition and removal of packages to/from an existing installation.
\end{itemize}
\end{enumerate}

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.

\begin{figure}[htbp]\begin{center}\leavevmode
\tipimage{78pa_cycle}{248pt}
\caption{}
\end{center}\end{figure}

Examples:
\begin{itemize}
\item{}
Larry Virden is \textit{System-Administrator}, \textit{P/A Builder} and \textit{P/A User} for his organization.
\item{}
I (the author of this TIP) am all roles, on my system at home.
\item{}
ActiveState is \textit{Repository Manager} for the Perl community and plans to become one for the Tcl community.
\item{}
SourceForge is a combination of \textit{Repository Manager} and \textit{Catalog Manager}.
\item{}
Most people with a windows machine at home are \textit{System-Administration} and \textit{P/A User} for this machine.
\end{itemize}

\section{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:
\begin{itemize}
\item{}
Blue rounded boxes --- Areas of responsibility for roles. The responsible role is written in gold text inside of the box.
\item{}
White rounded boxes with a black border --- Data, like packages, distributions, etc.
\item{}
White boxes with a red border --- Actions on data.
\end{itemize}

\begin{figure}[htbp]\begin{center}\leavevmode
\tipimage{78tea_terms_relations_1}{941pt}
\caption{Roles, Data and Actions}
\end{center}\end{figure}

\begin{figure}[htbp]\begin{center}\leavevmode
\tipimage{78tea_terms_relations_2}{266pt}
\caption{Relationships Between Data Entities}
\end{center}\end{figure}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#34]{tip34}
Mo DeJong,
Andreas Kupries,
\emph{Modernize TEA Build System},
on-line at \url{http://purl.org/tcl/tip/34.html}
\end{thebibliography}
\end{document}
