From 86f77fc7602eed20df591dbb9b94b68bd3b5b007 Mon Sep 17 00:00:00 2001 From: michel-schinz Date: Mon, 8 Nov 2004 19:53:28 +0000 Subject: [PATCH] - document --phases (which now subsumes --install-only and --build-only), - document phase-active? predicate --- doc/latex/install-lib.tex | 51 +++++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/doc/latex/install-lib.tex b/doc/latex/install-lib.tex index 4152431..55d224d 100644 --- a/doc/latex/install-lib.tex +++ b/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{--build-only} & Only perform operations required to build the package, if any.\\ - \cloption{--install-only} & Only perform operations required to install the package.\\ + \cloption{--dest-dir} dir & Specify a prefix for all installed files\\ + \cloption{--phases} phases & Only perform some phases of installation.\\ \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 -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{--phases} option is used to perform only some steps of +the whole installation process. Currently, two phases are defined: +\phase{build} and \phase{install}. -The \cloption{--install-only} option is used to perform only the steps -required to install the package. +The \phase{build} phase is the one during which the operations +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 -``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: +The \phase{install} phase is the one during which the files are copied +to their final location. + +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 - \cloption{--build-only}. + except that \phase{install} has to be given to \cloption{--phases} + 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