\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#291: Add the 'platform' Package to Tcl}
\date{October 26, 2006}
\author{Steve Landers, Andreas Kupries}
\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 \#291}&\textbf{Add the 'platform' Package to Tcl}\\\hline
Author&

Steve Landers \tipmail{steve}{DigitalSmarties.com}
\par
Andreas Kupries \tipmail{andreask}{activestate.com}
\\
Created&Thursday, \(\text{26}^{\text{th}}\) October 2006\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.9 $\\
Keywords&Tcl, Critcl, TEApot\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding the \textbf{platform} package to the Tcl core sources and to install it automatically, similar to what is currently done with the \textbf{tcltest} package.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It has been shown by the current users of the \textbf{platform} package --- the \textbf{Critcl} (C Runtime in Tcl) and the \textbf{TEApot} repository system --- that it is useful to not only be able to identify the architecture of a machine running Tcl, but to condense this information into a single identifier, standardized across platforms.

Whilst Tcl provides the \textit{tcl\_platform} array for identifying the current architecture (in particular, the platform and machine elements) this is not always sufficient. This is because (on Unix machines) \textit{tcl\_platform} reflects the values returned by the \textbf{uname} command and these aren't standardized across platforms and architectures. In addition, on at least one platform (AIX) the \textit{tcl\_platform(machine)} contains the CPU serial number.

Consequently, individual applications need to manipulate the values in \textit{tcl\_platform} (along with the output of system specific utilities) --- which is both inconvenient for developers, and introduces the potential for inconsistencies in identifying architectures and in naming conventions.

Placing the \textbf{platform} package into the core in the same manner as \textbf{tcltest} will prevent such fragmentation --- i.e., it will establish a standard naming convention for architectures running Tcl --- and will make it more convenient for developers to identify the current architecture a Tcl program is running on.

\section{Specification of the proposed Change}

\subsection{Tcl Level API}

Two new packages, \textbf{platform} and \textbf{platform::shell} are made available, and can be loaded into Tcl via \textbf{package require}.

The package \textbf{platform} provides three commands:
\begin{enumerate}
\item{}
\textbf{::platform::identify}

This command returns an identifier describing the platform the Tcl core is running on.
\item{}
\textbf{::platform::generic}

This command returns a simplified identifier, leaving out details like kernel version, libc version, etc.
\item{}
\textbf{::platform::patterns} \textit{id}

This command takes an identifier as returned by \textbf{::platform::identify} and returns a list of identifiers for compatible architectures.
\end{enumerate}

All identifiers have the general format \textit{OS}-\textit{CPU}. The CPU part will not contain dashes anymore, whereas the OS part may contain dashes.

The package \textbf{platform::shell} provides three commands as well, two of which are wrappers around commands provided by \textbf{platform}.
\begin{enumerate}
\item{}
\textbf{::platform::shell::generic} \textit{shell}

This command returns the generic identification of the specified \textit{shell}. The shell has to be executable on the host machine, but does not have to have the package \textbf{platform} itself. This is supplied by the caller.
\item{}
\textbf{::platform::shell::identify} \textit{shell}

This command returns the exact identification of the specified \textit{shell}. The shell has to be executable on the host machine, but does not have to have the package \textbf{platform} itself. This is supplied by the caller.
\item{}
\textbf{::platform::shell::platform} \textit{shell}

This command returns the contents of \textit{tcl\_platform(platform)} for the specified \textit{shell}. The shell has to be executable on the host machine.
\end{enumerate}

\subsection{Public C API}

One deficiency in the current implementation of the package \textit{platform} is the difficulty of distinguishing 64bit and 32bit systems. To remove this deficiency the variable \textit{tcl\_platform} of the Tcl core is extended to contain an entry \textit{pointerSize}. The value associated with this entry is the number of bytes needed by the machine to store a \textit{void *} pointer.

\section{Discussion}

When choosing the format for platform identifiers we had two contenders, i.e. \textit{OS}-\textit{CPU} vs. \textit{CPU}-\textit{OS}, the second of which is used by GCC. However for developers using a scripting language like Tcl the OS is of more importance than the CPU architecture. Because of this the first form was chosen.

\section{Reference Implementation}

This is available on SourceForge [\url{http://sourceforge.net/support/tracker.php?aid=1600701}].

\section{Copyright}

This document has been placed in the public domain.

Please note that any correspondence to the author concerning this TIP is considered in the public domain unless otherwise specifically requested by the individual(s) authoring said correspondence. This is to allow information about the TIP to be placed in a public forum for discussion.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
