diff --git a/doc/latex/proposal.tex b/doc/latex/proposal.tex index 40e52d7..2c5e53b 100644 --- a/doc/latex/proposal.tex +++ b/doc/latex/proposal.tex @@ -1,4 +1,4 @@ -%% $Id: proposal.tex,v 1.2 2004/02/29 20:00:47 michel-schinz Exp $ +%% $Id: proposal.tex,v 1.3 2004/03/21 16:21:55 michel-schinz Exp $ %% TODO %% - clean up permissions mess @@ -114,6 +114,8 @@ The unpacking directory contains at least the following files: \begin{description} \item[\file{install-pkg}] a script performing the installation of the package, +\item[\file{pkg-def.scm}] a Scheme file containing the installation + procedure for the package (see §~\ref{sec:authoring-packages}), \item[\file{README}] a textual file containing a short description of the package, \item[\file{COPYING}] a textual file containing the license of the @@ -193,24 +195,34 @@ to a \emph{prefix}, specified at installation time using the \file{COPYING} which has to be installed in sub-directory \file{license} of the \location{doc} location. If the user chooses to use the default layout, which maps \location{doc} to directory - \file{/doc} (see §~\ref{sec:scsh-layout}), and - specifies \file{/usr/local/share/scsh/modules} as a prefix, then the + \file{//doc} (see + §~\ref{sec:scsh-layout}), and specifies + \file{/usr/local/share/scsh/modules} as a prefix, then the \file{COPYING} file will end up in: \[ -\underbrace{\mathtt{/usr/local/share/scsh/modules/}}_{1}% -\underbrace{\mathtt{foo-1.2/doc/}}_{2}% -\underbrace{\mathtt{license/COPYING}}_{3} +\begin{small} +\underbrace{\mbox{\texttt{/usr/local/share/scsh/modules/}}}_{1}% +\underbrace{\mbox{\texttt{0.6/foo-1.2/doc/}}}_{2}% +\underbrace{\mbox{\texttt{license/COPYING}}}_{3} +\end{small} \] -Part 1 is the prefix, part 2 is the layout's mapping for the -\location{doc} location, and part 3 is the file name relative to the -location. +(provided the user is running scsh v0.6.x) Part 1 is the prefix, part +2 is the layout's mapping for the \location{doc} location, and part 3 +is the file name relative to the location. \end{example} \subsubsection{Predefined layouts} \label{sec:predefined-layouts} Every installation script comes with a set of predefined layouts which -serve different aims. They are described below. +serve different aims. They are described below + +The directories to which these layouts map locations often have a name +which includes the current version of scsh and/or the full name of the +package. In what follows, the notation \file{} represents the +printed representation of the first two components of scsh's version +(e.g. \file{0.6} for scsh v0.6.x). The notation \file{} +represents the \emph{full} name of the package being installed. \paragraph{The \layout{scsh} layout} \label{sec:scsh-layout} @@ -222,19 +234,18 @@ package being installed. Its name is simply the full name of the package in question, and it resides in the \file{prefix} directory. The \layout{scsh} layout maps locations as given in the following -table, where \file{} stands for the full name of -the package: +table: \begin{center} \begin{tabular}{|l|l|} \hline - \textbf{Location} & \textbf{Directory (relative to prefix)}\\ + \textbf{Location} & \textbf{Directory (relative to prefix)} \\ \hline - \location{base} & \file{} \\ - \location{active} & \file{.} \\ - \location{scheme} & \file{/scheme} \\ - \location{lib} & \file{/lib} \\ - \location{doc} & \file{/doc} \\ - \location{misc-shared} & \file{} \\ + \location{base} & \file{/} \\ + \location{active} & \file{} \\ + \location{scheme} & \file{//scheme} \\ + \location{lib} & \file{//lib} \\ + \location{doc} & \file{//doc} \\ + \location{misc-shared} & \file{/} \\ \hline \end{tabular} \end{center} @@ -253,14 +264,14 @@ Standard (FHS, see \href{http://www.pathname.com/fhs/}% \begin{center} \begin{tabular}{|l|l|} \hline - \textbf{Location} & \textbf{Directory (relative to prefix)}\\ + \textbf{Location} & \textbf{Directory (relative to prefix)} \\ \hline - \layout{base} & \file{share/scsh/modules/} \\ - \layout{active} & \file{share/scsh/modules} \\ - \layout{scheme} & \file{share/scsh/modules//scheme} \\ - \layout{lib} & \file{lib/scsh/modules/} \\ - \layout{doc} & \file{share/doc/} \\ - \layout{misc-shared} & \file{share/scsh/modules/} \\ + \layout{base} & \file{share/scsh-/modules/} \\ + \layout{active} & \file{share/scsh-/modules} \\ + \layout{scheme} & \file{share/scsh-/modules//scheme} \\ + \layout{lib} & \file{lib/scsh-/modules/} \\ + \layout{doc} & \file{share/doc/scsh-/} \\ + \layout{misc-shared} & \file{share/scsh-/modules/} \\ \hline \end{tabular} \end{center} @@ -364,15 +375,15 @@ as this forces scsh to search them recursively. This could scsh packages according to the \layout{fhs} layout in prefix directory \file{/usr/local}. The \location{active} location for these packages corresponds to the directory - \file{/usr/local/share/scsh/modules}, according to section + \file{/usr/local/share/scsh-0.6/modules}, according to section \ref{sec:fhs-layout}. Let's also imagine that there is a user called \texttt{john} on this machine, who installs additional scsh packages for himself in his - home directory, using \file{/home/john/scsh-packages} as a prefix. + home directory, using \file{/home/john/scsh} as a prefix. To ease their management, he uses the \layout{scsh} layout. The \location{active} location for these packages corresponds to the - directory \file{/home/john/scsh-packages}, according to section + directory \file{/home/john/scsh/0.6}, according to section \ref{sec:scsh-layout}. In order to be able to use scsh packages installed both by the @@ -381,7 +392,7 @@ as this forces scsh to search them recursively. This could variable. The value of this variable will therefore be: \begin{small} \begin{verbatim} -"/usr/local/share/scsh/modules" "/home/john/scsh-packages" +"/usr/local/share/scsh-0.6/modules" "/home/john/scsh/0.6" \end{verbatim} \end{small} @@ -395,6 +406,7 @@ as this forces scsh to search them recursively. This could \end{example} \section{Authoring packages} +\label{sec:authoring-packages} Once the Scheme and/or C code for a package has been written, the last step in turning it into a standard package as defined by this proposal @@ -452,13 +464,27 @@ The installation statements typically use functions of the installation library in order to install files in their target location. The available functions are presented below. -\param{Extensions} is currently used only to specify additional -command-line arguments, but in the future it could serve other -purposes. It consists in a list of lists, each one starting with a -symbol identifying the extension, followed by extension-specific -parameters. - +\param{Extensions} consists in a list of lists, each one starting with +a symbol identifying the extension, possibly followed by +extension-specific parameters. It is used to specify various +parameters, which are usually optional. Currently, the following +extensions are defined: \begin{description} +\item[install-lib-version] specifies the version of the installation + library that this package definition requires. The version is + specified as a list composed of \emph{exactly two} integers, giving + the major and minor version number of the library. Before installing + a package, this version requirement is checked and installation + aborts if the installation library does not satisfy it.% + \footnote{Version $(i_1\,i_2)$ of the installation library satisfies a + requirement $(r_1\,r_2)$ if and only if both major numbers are equal, + and the minor number of the installation library is greater or + equal to the minor requirement. In other words, iff $i_1 = r_1$ + and $i_2 \ge r_2$.}% + It is strongly recommended that package authors provide this + information, as it makes it possible to provide helpful error + messages to users. + \item[options] enables the script to define additional command-line options. It accepts nine parameters in total, with the last three being optional. The description of these parameters follows, in the @@ -647,4 +673,12 @@ to their final location by the system packaging tools. %% (Abstract) location %% Package loading script +\section{Acknowledgments} +\label{sec:acknowledgments} + +Discussions with Andreas Bernauer, Anthony Carrico, David Frese, +Martin Gasbichler, Eric Knauel and Daniel Kobras greatly helped the +design of this proposal. Mark Sapa started everything by asking for a +Fink package for sunet and sunterlib. + \end{document} \ No newline at end of file