From 4076ef436c98bcdb80b15879e9e3c3e2058a50f0 Mon Sep 17 00:00:00 2001 From: michel-schinz Date: Thu, 4 Nov 2004 14:18:38 +0000 Subject: [PATCH] - changed package naming scheme: forbid underscores, allow hypens, - added distinction between stand-alone and split packages, - described new options --build-only and --install-only. --- doc/latex/install-lib.tex | 144 +++++++++++++++++++++++++++++++------- 1 file changed, 117 insertions(+), 27 deletions(-) diff --git a/doc/latex/install-lib.tex b/doc/latex/install-lib.tex index d27d018..4152431 100644 --- a/doc/latex/install-lib.tex +++ b/doc/latex/install-lib.tex @@ -1,7 +1,6 @@ -%% $Id: install-lib.tex,v 1.2 2004/06/13 17:51:15 michel-schinz Exp $ +%% $Id: install-lib.tex,v 1.3 2004/11/04 14:18:38 michel-schinz Exp $ %% TODO -%% - clean up permissions mess \documentclass[a4paper,12pt]{article} @@ -54,9 +53,9 @@ be outside of its scope. Packages are identified by a globally-unique name. This name should start with an ASCII letter (a-z or A-Z) and should consist only of -ASCII letters, digits or underscore characters `\verb|_|'. Package -names are case-sensitive, but there should not be two packages with -names which differ only by their capitalisation. +ASCII letters, digits or hyphens `\verb|-|'. Package names are +case-sensitive, but there should not be two packages with names which +differ only by their capitalisation. \begin{rationale} This restriction on package names ensures that they can be used to @@ -90,9 +89,19 @@ context. \section{Distributing packages} -Packages are distributed in \texttt{tar} archives, which can -optionally be compressed by \texttt{gzip} or \texttt{bzip2}. The name -of the archive is composed by appending: +Packages are usually distributed as a stand-alone archive containing +the code and documentation to install, as well as a file describing +the installation procedure. However, it is also possible to distribute +the scsh-specific installation procedure separately from the main code +and documentation. This is typically useful to turn general Scheme +libraries into scsh packages. + +\subsection{Stand-alone packages} +\label{sec:stand-alone-packages} + +Stand-alone packages are distributed in a single \texttt{tar} archive, +which can optionally be compressed by \texttt{gzip} or \texttt{bzip2}. +The name of the archive is composed by appending: \begin{itemize} \item the full name of the package, \item the string \texttt{.tar} indicating that it's a \texttt{tar} @@ -103,12 +112,10 @@ of the archive is composed by appending: compressed. \end{itemize} -\subsection{Archive contents} - -The archive is organised so that it contains one top-level directory -whose name is the full name of the package. This directory is called -the \emph{package unpacking directory}. All the files belonging to the -package are stored below it. +The archive of a stand-alone package is organised so that it contains +one top-level directory whose name is the full name of the package. +This directory is called the \emph{package unpacking directory}. All +the files belonging to the package are stored below it. The unpacking directory contains at least the following files: \begin{description} @@ -120,6 +127,49 @@ The unpacking directory contains at least the following files: package. \end{description} +\subsection{Split packages} +\label{sec:split-packages} + +Split packages are distributed as two separate archives. The first +one, called the \emph{upstream archive}, contains the code and +documentation of the package. The second one, called the +\emph{downstream archive}, contains the scsh-specific installation +procedure for the package. + +Ideally, the upstream archive should follow the rules laid out in the +previous section for stand-alone archives. Most of the time, however, +the author of the upstream package has no reason to be aware of the +current policy, or simply to adhere to it. The name and layout of the +downstream archive should therefore mirror the one of the upstream +archive, as follows: +\begin{enumerate} +\item the name of the downstream archive is composed by appending: + \begin{itemize} + \item the string \texttt{pkg\_} (the three letters `p', `k' and `g' + followed by an underscore character), + \item the name of the upstream archive, including its version but + excluding extensions indicating the archive type and/or + compression method, + \item an underscore character, + \item a single number indicating the version of the downstream + archive, + \item the string \texttt{.tar} indicating that it's a \texttt{tar} + archive, + \item either the string \texttt{.gz} if the archive is compressed + using \texttt{gzip}, or the string \texttt{.bz2} if the archive is + compressed using \texttt{bzip2}, or nothing if the archive is not + compressed. + \end{itemize} +\item the downstream archive should contain at least the file + \file{pkg-def.scm} placed in a directory with the same name as the + ``main'' directory of the upstream archive. +\end{enumerate} +These conventions ensure that split packages behave almost like +stand-alone packages after the two archives have been unpacked at the +same location. + +% TODO give an example of a split package + \section{Downloading and installing packages} A package can be installed on a target machine by downloading its @@ -305,6 +355,8 @@ accepts the following options: \cloption{--no-user-defaults} & Don't read user defaults in \file{.scsh-pkg-defaults.scm} (see §~\ref{sec:user-preferences}). \\ \end{tabular} \end{center} +A few, more advanced options exist and are documented in section +\ref{sec:packaging-packages}. \subsubsection{User preferences} \label{sec:user-preferences} @@ -659,6 +711,7 @@ strongly encouraged to use it. %% major problem thanks to scsh's ability to run separate programs. \section{Packaging packages} +\label{sec:packaging-packages} Most important Unix systems today have one (or several) package management systems which ease the installation of packages on a @@ -668,18 +721,46 @@ scsh packages discussed above, they will be called \emph{system It makes perfect sense to provide system packages for scsh packages. System packages should as much as possible try to use the standard -installation script described above to install scsh packages. This -script currently provides some support for staged installations, which -are required by several packaging systems. +installation script described above to install scsh packages. In order +to make this as easy as possible, the installation script recognizes +the following additional options: -This support is provided through an additional option, -\cloption{--dest-dir}, which specifies the root directory in which to -install files. The files will then have to be moved from this location -to their final location by the system packaging tools. +\begin{center} + \begin{tabular}{lp{.6\textwidth}} + \cloption{--dest-dir} dir & Specify a prefix for all installed files\\ + \cloption{--build-only} & Only perform operations required to build the package, if any.\\ + \cloption{--install-only} & Only perform operations required to install the package.\\ + \end{tabular} +\end{center} -(The \cloption{--dest-dir} option plays the same role as the +The \cloption{--dest-dir} option plays the same role as the \envvar{DESTDIR} variable which is typically given to \texttt{make - install}, for makefiles which support staging directories). + install}. Its value, which is the empty string by default, is +prepended to all installation paths. This is used to perform staged +installations, during which the package is first installed into a +temporary directory and then moved to its final location by some +external tool. + +The \cloption{--build-only} option is used to perform only the steps +required to build the package. For scsh packages containing only +Scheme code, this generally means doing nothing. For scsh packages +containing some C code, this usually means invoking \texttt{make} but +not \texttt{make install}. + +The \cloption{--install-only} option is used to perform only the steps +required to install the package. + +These two options can be used one after the other to perform +``installation'' as two separate steps, possibly with a different user +identity. In order for this to work correctly, the installation script +\emph{must} be invoked twice, as follows: +\begin{enumerate} +\item first with the \cloption{--build-only} option and maybe other + options, +\item then with the \emph{exact same options} as in the first step, + except that \cloption{--install-only} has to be specified instead of + \cloption{--build-only}. +\end{enumerate} %% \section{Glossary} %% TODO define the following terms @@ -694,9 +775,18 @@ to their final location by the system packaging tools. \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. +Discussions with +Andreas Bernauer, +Anthony Carrico, +David Frese, +Friedrich Delgado Friedrichs, +Martin Gasbichler, +Eric Knauel, +Daniel Kobras, +Lionel Elie Mamane, and +Jorgen Schäfer +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