- 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

@@ -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
+ASCII letters, digits or hyphens `\verb|-|'. Package names are
-names are case-sensitive, but there should not be two packages with
+case-sensitive, but there should not be two packages with names which
-names which differ only by their capitalisation.
+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
+Packages are usually distributed as a stand-alone archive containing
-optionally be compressed by \texttt{gzip} or \texttt{bzip2}. The name
+the code and documentation to install, as well as a file describing
-of the archive is composed by appending:
+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 of a stand-alone package is organised so that it contains
-
+one top-level directory whose name is the full name of the package.
-The archive is organised so that it contains one top-level directory
+This directory is called the \emph{package unpacking directory}. All
-whose name is the full name of the package. This directory is called
+the files belonging to the package are stored below it.
-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
+installation script described above to install scsh packages. In order
-script currently provides some support for staged installations, which
+to make this as easy as possible, the installation script recognizes
-are required by several packaging systems.
+the following additional options:
 
-This support is provided through an additional option,
+\begin{center}
-\cloption{--dest-dir}, which specifies the root directory in which to
+  \begin{tabular}{lp{.6\textwidth}}
-install files. The files will then have to be moved from this location
+    \cloption{--dest-dir} dir & Specify a prefix for all installed files\\
-to their final location by the system packaging tools.
+    \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,
+Discussions with
-Martin Gasbichler, Eric Knauel and Daniel Kobras greatly helped the
+Andreas Bernauer,
-design of this proposal. Mark Sapa started everything by asking for a
+Anthony Carrico,
-Fink package for sunet and sunterlib.
+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}