- document --phases (which now subsumes --install-only and

--build-only),
- document phase-active? predicate

doc/latex/install-lib.tex

@@ -1,4 +1,4 @@
-%% $Id: install-lib.tex,v 1.3 2004/11/04 14:18:38 michel-schinz Exp $
+%% $Id: install-lib.tex,v 1.4 2004/11/08 19:53:28 michel-schinz Exp $
 
 %% TODO
 
@@ -15,6 +15,7 @@
 \newcommand{\layout}[1]{\texttt{#1}}
 \newcommand{\location}[1]{\texttt{#1}}
 \newcommand{\ident}[1]{\texttt{#1}}
+\newcommand{\phase}[1]{\texttt{#1}}
 
 \newcommand{\define}[3]{%
   \noindent%
@@ -622,6 +623,14 @@ Return the value of the given command-line \param{option} (a symbol).
 This can be used to get the value of predefined options (like
 \cloption{--dry-run}) or package-specific options.
 
+\vspace{1em}
+\definep{phase-active?}{phase}%
+Return true iff the given \param{phase} is active, that is if the
+steps associated with it should be performed. \param{Phase} should be
+either the symbol \texttt{build} or the symbol \texttt{install},
+designating the corresponding phase (see section
+\ref{sec:packaging-packages}).
+
 \subsubsection{Load script generation}
 
 \definep{with-output-to-load-script*}{thunk}%
@@ -727,9 +736,8 @@ the following additional options:
 
 \begin{center}
   \begin{tabular}{lp{.6\textwidth}}
-    \cloption{--dest-dir} dir & Specify a prefix for all installed files\\
+    \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{--phases} phases & Only perform some phases of installation.\\
-    \cloption{--install-only} & Only perform operations required to install the package.\\
   \end{tabular}
 \end{center}
 
@@ -741,26 +749,33 @@ 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
+The \cloption{--phases} option is used to perform only some steps of
-required to build the package. For scsh packages containing only
+the whole installation process. Currently, two phases are defined:
-Scheme code, this generally means doing nothing. For scsh packages
+\phase{build} and \phase{install}.
-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
+The \phase{build} phase is the one during which the operations
-required to install the package.
+required to build the package are performed. For scsh packages
+containing only Scheme code, this phase usually does nothing. For scsh
+packages containing some C code, this phase is the one during which
+the C code is compiled.
 
-These two options can be used one after the other to perform
+The \phase{install} phase is the one during which the files are copied
-``installation'' as two separate steps, possibly with a different user
+to their final location.
-identity. In order for this to work correctly, the installation script
+
-\emph{must} be invoked twice, as follows:
+Using the \cloption{--phases} option, each phase can happen during a
+separate run of the installation script. This makes it possible, for
+example, to perform the build phase as one user, and the install phase
+as another one (e.g. root). In order for this to work, the
+installation script must be invoked as follows:
 \begin{enumerate}
-\item first with the \cloption{--build-only} option and maybe other
+\item first with the \cloption{--phases build} 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
+  except that \phase{install} has to be given to \cloption{--phases}
-  \cloption{--build-only}.
+  instead of \phase{build}.
 \end{enumerate}
+The behaviour of the installation script is not defined if these
+conditions are violated.
 
 %% \section{Glossary}
 %% TODO define the following terms