scsh-conservatory
/
scsh-install-lib
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- changed package naming scheme: forbid underscores, allow hypens, 

- added distinction between stand-alone and split packages,
- described new options --build-only and --install-only.
This commit is contained in:
michel-schinz 2004-11-04 14:18:38 +00:00
parent 2308badf7a
commit 4076ef436c
1 changed files with 117 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
doc/latex/install-lib.tex
View File

@ -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}