- introduced layouts
This commit is contained in:
michel-schinz
parent
ebc512096b
commit
19754f5cdf
394
doc/proposal.txt
394
doc/proposal.txt
|
|
@ -75,13 +75,13 @@ package are stored below it.
|
|||
|
||||
The unpacking directory contains at least the following files:
|
||||
|
||||
- install-pkg
|
||||
install-pkg
|
||||
a script performing the installation of the package,
|
||||
|
||||
- README
|
||||
README
|
||||
a textual file containing a short description of the package,
|
||||
|
||||
- COPYING
|
||||
COPYING
|
||||
a textual file containing the license of the package.
|
||||
|
||||
* Downloading and installation of packages
|
||||
|
|
@ -90,102 +90,46 @@ A package can be installed on a target machine by downloading its
|
|||
archive, expanding it and finally running the installation script
|
||||
located in the unpacking directory.
|
||||
|
||||
All files belonging to a package will be installed in a single
|
||||
directory called the "package installation directory". The package
|
||||
installation directory contains all files, and only files belonging to
|
||||
the (version of the) package.
|
||||
** Layouts
|
||||
|
||||
Rationale:
|
||||
The installation script installs files according to some given layout.
|
||||
A layout maps abstract locations to concrete directories on the target
|
||||
machine. For example, a layout could map the abstract location "doc"
|
||||
(where documentation is stored) to the directory
|
||||
"/usr/local/share/doc/my_package".
|
||||
|
||||
Such an organisation makes it easy to uninstall package by just
|
||||
recursively deleting a single directory. It also makes it trivial to
|
||||
know to which package a given file belongs.
|
||||
Currently, the following abstract locations are defined:
|
||||
|
||||
** Root directory layout
|
||||
base
|
||||
|
||||
The package installation directory will be an indirect sub-directory
|
||||
of some "package root directory". A package root directory is a
|
||||
directory on the target machine which contains all installed packages.
|
||||
There can be several package roots on a target machine, for example
|
||||
one for packages installed globally, and one per user for "personal"
|
||||
packages.
|
||||
The "base" location of a package, where the package loading
|
||||
script "load.scm" resides.
|
||||
|
||||
A package root directory contains exactly two sub-directories, and
|
||||
nothing else. These directories are called "installed" and "active".
|
||||
active
|
||||
|
||||
The "installed" directory contains exactly one directory per package,
|
||||
and nothing else (N.B. here "package" really means "package" and not
|
||||
"package version"). These directories have the same name as the
|
||||
package they contain. For every installed version of a package, there
|
||||
is a sub-directory of the package directory. These directories are
|
||||
named using the printed representation of the version they contain.
|
||||
Location containing a symbolic link, with the same name as the
|
||||
package (without the version), pointing to the "base" location of
|
||||
the package. This link is used to designate the "active" version
|
||||
of a package, that is the one to load when a package is requested
|
||||
by giving only its name, without explicit version.
|
||||
|
||||
The "active" directory contains only symbolic links which point to
|
||||
package version directories. There is at most one symbolic link per
|
||||
installed package. These symbolic links identify the active (or
|
||||
default) version of a package, that is the version will be used if a
|
||||
script asks for a given package without explicitly which version is
|
||||
required.
|
||||
scheme
|
||||
|
||||
Example:
|
||||
Location containing all Scheme code. If the package comes with
|
||||
some examples showing its usage, they are put in a sub-directory
|
||||
called "examples" of this location.
|
||||
|
||||
Let's imagine a system on which the directory
|
||||
"/usr/local/lib/scsh/modules" serves as the package root directory. On
|
||||
this system, versions 1.0 and 2.0 of a package called "package_1" are
|
||||
installed, the latter being active. Further, version 1.5.4 of a
|
||||
package called "package_2" is installed and active. The contents of
|
||||
the package root would look as follows:
|
||||
lib
|
||||
|
||||
/usr/local/lib/scsh/modules/
|
||||
installed/
|
||||
package_1/
|
||||
1.0/
|
||||
all files belonging to v1.0 of package_1 (and nothing else)
|
||||
2.0/
|
||||
all files belonging to v2.0 of package_1
|
||||
package_2/
|
||||
1.5.4/
|
||||
all files belonging to v1.5.4 of package_2
|
||||
active/
|
||||
package_1 -> ../installed/package_1/2.0
|
||||
package_2 -> ../installed/package_2/1.5.4
|
||||
Location containing platform-dependent libraries.
|
||||
|
||||
** Package directory layout
|
||||
doc
|
||||
|
||||
Even though the exact contents of the package directory will depend on
|
||||
the package, all package directories are laid out according to the
|
||||
rules below. These rules make it easy to examine the contents of a
|
||||
package directory, and find important data like the package
|
||||
documentation.
|
||||
|
||||
The standard layout is shown below. Some directories are of course
|
||||
optional because not all packages have something to put in all of
|
||||
them.
|
||||
|
||||
load.scm
|
||||
|
||||
Scheme file written in Scheme 48's exec language, whose role is to
|
||||
define all the structures which belong to a package.
|
||||
|
||||
scheme/
|
||||
|
||||
Directory containing all the Scheme code of the package.
|
||||
|
||||
lib/
|
||||
|
||||
Directory containing one sub-directory per platform for which the
|
||||
package was installed. These sub-directories contain the shared
|
||||
libraries for the given platform; the name of a given platform is
|
||||
the one given by autoconf's "config.guess" script.
|
||||
|
||||
<platform>/
|
||||
|
||||
Directory containing the shared libraries for <platform>.
|
||||
|
||||
doc/
|
||||
|
||||
Directory containing the documentation of the package, possibly in
|
||||
different formats.
|
||||
Location containing all the package documentation. This location
|
||||
contains one or more sub-directories which store the documentation
|
||||
in various formats. The contents of these sub-directories is
|
||||
standardised as follows, to make it easy for users to find the
|
||||
document they need:
|
||||
|
||||
html/
|
||||
|
||||
|
|
@ -202,9 +146,85 @@ them.
|
|||
ps/
|
||||
|
||||
Directory containing the PostScript documentation of the
|
||||
package, if any; this directory should contain at least one file
|
||||
called "<package>.ps" where "<package>" is the name of the
|
||||
package.
|
||||
package, if any; this directory should contain at least one
|
||||
file called "<package>.ps" where "<package>" is the name of
|
||||
the package.
|
||||
|
||||
misc-shared
|
||||
|
||||
Location containing miscellaneous data which does not belong to
|
||||
any directory above, and which is platform-independant.
|
||||
|
||||
The directories to which a layout maps these abstract locations are
|
||||
not absolute directories, but rather relative ones. Therefore, a
|
||||
layout alone is not enough to know where files will end up on the
|
||||
target machine: a prefix is also required. This prefix is specified on
|
||||
the command-line during installation, using the "--prefix" option, as
|
||||
explained below.
|
||||
|
||||
Example :
|
||||
|
||||
Let's imagine that a user is installing version 1.2 of a package
|
||||
called "foo". This package contains a file called "COPYING" which has
|
||||
to be installed in sub-directory "license" of the "doc" location. If
|
||||
the user chooses to use the default layout, which maps "doc" to
|
||||
directory "<package_full_name>/doc" (see below), and specifies
|
||||
"/usr/local/etc/scsh/modules" as a prefix, then the "COPYING" file
|
||||
will end up in:
|
||||
|
||||
/usr/local/etc/scsh/modules/foo-1.2/doc/license/COPYING
|
||||
\_________________________/ \_________/ \_____________/
|
||||
1 2 3
|
||||
|
||||
Part 1 is the prefix, part 2 is the layout's mapping for the "doc"
|
||||
location, and part 3 is the file name relative to the location.
|
||||
|
||||
*** Predefined layouts
|
||||
|
||||
Every installation script comes with a set of predefined layouts
|
||||
which serve different aims. They are described below.
|
||||
|
||||
**** The "scsh" layout
|
||||
|
||||
The "scsh" layout is the default layout. It maps all locations to
|
||||
sub-directories of a single directory, called the package installation
|
||||
directory, which contains all the files of the package being installed
|
||||
and nothing else. Its name is simply the full name of the package in
|
||||
question, and it resides in the "prefix" directory.
|
||||
|
||||
The "scsh" layout maps locations as follows:
|
||||
|
||||
base -> <prefix>/<package_full_name>
|
||||
active -> <prefix>
|
||||
scheme -> <prefix>/<package_full_name>/scheme
|
||||
lib -> <prefix>/<package_full_name>/lib/<platform>
|
||||
doc -> <prefix>/<package_full_name>/doc
|
||||
misc-shared -> <prefix>/<package_full_name>
|
||||
|
||||
This layout is well suited for installations performed without the
|
||||
assistance of an additional package manager, because it makes many
|
||||
common operations easy. For example, finding to which package a file
|
||||
belongs is trivial, as is the removal of an installed package.
|
||||
|
||||
**** The "fhs" layout
|
||||
|
||||
The "fhs" layout maps locations according to the File Hierarchy
|
||||
Standard (FHS, see ...), as follows:
|
||||
|
||||
base -> <prefix>/share/scsh/modules/<package_full_name>
|
||||
active -> <prefix>/share/scsh/modules
|
||||
scheme -> <prefix>/share/scsh/modules/<package_full_name>/scheme
|
||||
lib -> <prefix>/lib/scsh/modules/<package_full_name>
|
||||
doc -> <prefix>/share/doc/<package_full_name>
|
||||
misc-shared -> <prefix>/share/scsh/modules/<package_full_name>
|
||||
|
||||
The main advantage of this layout is that it adheres to the FHS
|
||||
standard, and is therefore compatible with several packaging policies,
|
||||
like Debian's, Fink's and others. Its main drawback is that files
|
||||
belonging to a given package are scattered, and therefore hard to find
|
||||
when removing or upgrading a package. Its use should therefore be
|
||||
considered only if third-party tools are available to track files
|
||||
belonging to a package.
|
||||
|
||||
** File permissions
|
||||
|
||||
|
|
@ -213,16 +233,19 @@ TODO
|
|||
** Installation procedure
|
||||
|
||||
Packages are installed using the "install-pkg" script located in the
|
||||
package archive. This script must be given the name of the root
|
||||
directory in which to perform installation with the "--root" option.
|
||||
It also accepts the following options:
|
||||
package archive. This script must be given the name of the prefix
|
||||
using the "--prefix" option. It also accepts the following options:
|
||||
|
||||
--dry-run or -n
|
||||
--layout <name>
|
||||
|
||||
Specifies the layout to use.
|
||||
|
||||
--dry-run
|
||||
|
||||
Print what actions would be performed to install the package, but
|
||||
do not perform them.
|
||||
|
||||
--inactive or -i
|
||||
--inactive
|
||||
|
||||
Do not activate package after installing it.
|
||||
|
||||
|
|
@ -238,8 +261,8 @@ TODO (my current idea is to add support to install-lib to easily
|
|||
|
||||
To use a package, its "loading script" must be loaded in Scheme 48's
|
||||
exec package. The loading script for a package is a file written in
|
||||
the Scheme 48 exec language, whose name is "load.scm" and which is
|
||||
located directly in the package installation directory.
|
||||
the Scheme 48 exec language, whose name is "load.scm" and which
|
||||
resides in the "base" location.
|
||||
|
||||
To load this file, one typically uses scsh's "-lel" option along with
|
||||
a properly defined SCSH_LIB_DIRS environment variable.
|
||||
|
|
@ -251,27 +274,40 @@ configuration, and this value can be overridden by setting the
|
|||
environment variable SCSH_LIB_DIRS before running scsh.
|
||||
|
||||
In order for scsh to find the package loading scripts, one must make
|
||||
sure that scsh's library search path contains the names of both the
|
||||
"installed" and the "active" directories of *every* existing package
|
||||
root directories.
|
||||
|
||||
Example:
|
||||
|
||||
On a system where the package root directory is
|
||||
"/usr/local/lib/scsh/modules", the SCSH_LIB_DIRS environment variable
|
||||
has to contain at least the following two directories:
|
||||
|
||||
/usr/local/lib/scsh/modules/active
|
||||
/usr/local/lib/scsh/modules/installed
|
||||
sure that scsh's library search path contains the names of all
|
||||
"active" locations which containing packages.
|
||||
|
||||
The names of these directories should not end with a slash (/), as
|
||||
this forces scsh to search them recursively. This could *drastically*
|
||||
slow down scsh when looking for packages.
|
||||
|
||||
A package named "foo" can then be used from a script provided that the
|
||||
following option is added to its command line:
|
||||
Example:
|
||||
|
||||
-lel foo/load.scm
|
||||
Let's imagine a machine on which the system administrator installs
|
||||
scsh packages according to the "fhs" layout in prefix directory
|
||||
"/usr/local". The "active" location for these packages corresponds to
|
||||
the directory "/usr/local/share/scsh/modules", according to the layout
|
||||
specification above.
|
||||
|
||||
Let's also imagine that there is a user called "john" on this machine,
|
||||
who installs additional scsh packages for himself in his home
|
||||
directory, using "/home/john/scsh-packages" as a prefix. To ease their
|
||||
management, he uses the "scsh" layout. The "active" location for these
|
||||
packages corresponds to the directory "/home/john/scsh-packages",
|
||||
according to the layout specification above.
|
||||
|
||||
In order to be able to use scsh packages installed both by the
|
||||
administrator and by himself, user "john" needs to put both active
|
||||
directories in his SCSH_LIB_DIRS environment variable. The value of
|
||||
this variable will therefore be:
|
||||
|
||||
"/usr/local/share/scsh/modules" "/home/john/scsh-packages"
|
||||
|
||||
Now, in order to use packages "foo" and "bar" in one of his script,
|
||||
user "john" just needs to load their loading script using the -lel
|
||||
option when invoking scsh, as follows:
|
||||
|
||||
-lel foo/load.scm -lel bar/load.scm
|
||||
|
||||
* Writing packages
|
||||
|
||||
|
|
@ -284,26 +320,28 @@ to simplify this task a small scsh installation framework is provided.
|
|||
This framework is composed of several files which are meant to be
|
||||
included in the package archive. These files are:
|
||||
|
||||
- install-pkg
|
||||
|
||||
install-pkg
|
||||
a trivial sh script which launches scsh on the main function of
|
||||
the installation library, passing it all the arguments given by
|
||||
the user,
|
||||
|
||||
- install-lib.scm
|
||||
|
||||
the code for the installation library, documented below,
|
||||
|
||||
- install-lib-module.scm
|
||||
install-lib.scm
|
||||
the code for the installation library, whose public interface is
|
||||
documented below,
|
||||
|
||||
install-lib-module.scm
|
||||
Scheme 48 interface and structure definitions for the installation
|
||||
library.
|
||||
library,
|
||||
|
||||
configure.scm
|
||||
a Scheme library providing a function to query the name of the
|
||||
platform, needed by some layouts.
|
||||
|
||||
As explained above, when the install-pkg script is invoked, it launches
|
||||
scsh on the main function of the installation library, which does the
|
||||
following:
|
||||
|
||||
- parse the command line arguments (e.g the --root option),
|
||||
- parse the command line arguments (e.g the --prefix option),
|
||||
|
||||
- load the package definition file, a (Scheme) file called
|
||||
"pkg-def.scm", which is supplied by the package author and which
|
||||
|
|
@ -322,81 +360,119 @@ specifies the name, version and installation code for the package. The
|
|||
package definition statement is expressed using the following syntax
|
||||
exported from the installation library:
|
||||
|
||||
(define-package <name> <version> <body> ...) (syntax)
|
||||
(define-package <name> <version> <extensions> <body> ...) (syntax)
|
||||
|
||||
Define a package to be installed. NAME is the package name (a
|
||||
string), VERSION its version (a list of integers) and BODY is the
|
||||
list of statements to be evaluated in order to install the package.
|
||||
string), VERSION its version (a list of integers), EXTENSIONS is an
|
||||
association list of extensions, and BODY is the list of statements
|
||||
to be evaluated in order to install the package.
|
||||
|
||||
The installation statements typically use functions of the
|
||||
installation library in order to install files in their target
|
||||
location. The following functions are currently exported:
|
||||
|
||||
(install-file <file> [<target-dir>] [<perms>])
|
||||
(install-file <file> <location> [<target-dir>] [<perms>])
|
||||
|
||||
Install the given file in TARGET-DIR. TARGET-DIR is specified
|
||||
relative to the package directory, and defaults to "." (i.e. the
|
||||
package directory itself). If the target directory does not exist,
|
||||
it is created along with all its parents, as needed.
|
||||
Install the given FILE in the sub-directory TARGET-DIR (which must
|
||||
be a relative directory) of the given LOCATION.
|
||||
|
||||
If the directory in which the file is about to be installed does not
|
||||
exist, it is created along with all its parents, as needed. If FILE
|
||||
is a string, then the installed file will have the same name as the
|
||||
original one. If FILE is a pair, then its first element specifies
|
||||
the name of the source file, and its second element the name it will
|
||||
have once installed. The second element must be a simple file name,
|
||||
without any directory part.
|
||||
|
||||
The copied file and all directories created by this command have
|
||||
their permissions set to PERMS, an integer which defaults to #o755
|
||||
(i.e. read, write and execute for the owner, read and execute for
|
||||
the rest).
|
||||
|
||||
(install-files <file-list> [<target-dir>] [<perms>])
|
||||
(install-files <file-list> <location> [<target-dir>] [<perms>])
|
||||
|
||||
Like install-file but for several files, which are specified as a
|
||||
list.
|
||||
list. Each element in the list can be either a simple string or a
|
||||
pair, as explained above.
|
||||
|
||||
(install-directory <dir> [<target-dir>] [<perms>])
|
||||
(install-directory <dir> <location> [<target-dir>] [<perms>])
|
||||
|
||||
Install the given directory and all its contents, including
|
||||
sub-directories, in TARGET-DIR. This is similar to what INSTALL-FILE
|
||||
does, but for complete hierarchies.
|
||||
Install the given DIRectory and all its contents, including
|
||||
sub-directories, in sub-directory TARGET-DIR of LOCATION. This is
|
||||
similar to what INSTALL-FILE does, but for complete hierarchies.
|
||||
|
||||
Notice that DIR will be installed as a sub-directory of TARGET-DIR.
|
||||
|
||||
(install-directories <dir-list> [<target-dir>] [<perms>])
|
||||
(install-directories <dir-list> <location> [<target-dir>] [<perms>])
|
||||
|
||||
Install several directories in one go.
|
||||
|
||||
(install-directory-contents <dir> <location> [<target-dir>] [<perms>])
|
||||
|
||||
Install the *contents* of the given DIRectory in sub-directory
|
||||
TARGET of LOCATION.
|
||||
|
||||
An additional function exists to query the mapping of a location:
|
||||
|
||||
(get-directory <location> <install?>)
|
||||
|
||||
Get the absolute name of the directory to which the current layout
|
||||
maps the abstract LOCATION. If INSTALL? is true, the directory is
|
||||
the one valid during installation; If it is false, the directory is
|
||||
the one valid after installation, that is when the package is later
|
||||
used.
|
||||
|
||||
The distinction between installation-time and usage-time directories
|
||||
is necessary to support staged installation, as performed by package
|
||||
managers like Debian's APT.
|
||||
|
||||
Example:
|
||||
|
||||
A typical package definition file for a simple package called
|
||||
"my_package" whose version is 1.2 could look like this:
|
||||
|
||||
(define-package "my_package" (1 2)
|
||||
(install-file "load.scm")
|
||||
(install-directories '("scheme" "doc")))
|
||||
(install-file "load.scm" 'base)
|
||||
(install-directory-contents "scheme" 'scheme)
|
||||
(install-file ("LICENSE" . "COPYING") 'doc)
|
||||
(install-directory-contents "doc" 'doc))
|
||||
|
||||
With such a definition, invoking the installation script with
|
||||
"/usr/local/lib/scsh/modules" as package root would have the
|
||||
following effects:
|
||||
"/usr/local/" as prefix and "fhs" as layout would have the following
|
||||
effects:
|
||||
|
||||
1. The package directory
|
||||
1. The base directory
|
||||
|
||||
/usr/local/lib/scsh/modules/installed/my_package/1.2
|
||||
/usr/local/share/scsh/modules/my_package-1.2
|
||||
|
||||
would be created.
|
||||
|
||||
2. File "load.scm" would be copied to this directory.
|
||||
would be created and file "load.scm" would be copied to it.
|
||||
|
||||
3. All the contents of the directory called "scheme" would be copied
|
||||
to directory
|
||||
|
||||
/usr/local/lib/scsh/modules/installed/my_package/1.2/scheme
|
||||
/usr/local/share/scsh/modules/my_package-1.2/scheme
|
||||
|
||||
The same would happen for the contents of directory "doc".
|
||||
which would be created before, if needed.
|
||||
|
||||
4. The package would be activated by creating a symbolic link with
|
||||
4. File "LICENSE" would be copied to directory
|
||||
|
||||
/usr/local/share/doc/my_package-1.2/
|
||||
|
||||
with name "COPYING".
|
||||
|
||||
5. All the contents of the directory called "doc" would be copied to
|
||||
directory
|
||||
|
||||
/usr/local/share/doc/my_package-1.2/
|
||||
|
||||
6. The package would be activated by creating a symbolic link with
|
||||
name
|
||||
|
||||
/usr/local/lib/scsh/modules/active/my_package
|
||||
/usr/local/share/scsh/modules/my_package
|
||||
|
||||
pointing to
|
||||
|
||||
../installed/my_package/1.2
|
||||
./my_package-1.2
|
||||
|
||||
** Packages containing C code (for shared libraries)
|
||||
|
||||
|
|
@ -424,13 +500,13 @@ installation script described above to install scsh packages. This
|
|||
script currently provides some support for staged installations,
|
||||
which are required by several packaging systems.
|
||||
|
||||
This support is provided through an additional option, --dest-root,
|
||||
which specifies the package root in which the files have to be copied
|
||||
by the installation script. The files will then have to be moved from
|
||||
this location to their final root directory, i.e. the one given
|
||||
through the --root option, by the system packaging tools.
|
||||
This support is provided through an additional option,
|
||||
--install-prefix, which specifies the prefix in which the files have
|
||||
to be copied by the installation script. The files will then have to
|
||||
be moved from this location to their final prefix directory, i.e. the
|
||||
one given through the --prefix option, by the system packaging tools.
|
||||
|
||||
(The --dest-root option plays the same role as the DEST_DIR
|
||||
(The --install-prefix option plays the same role as the DEST_DIR
|
||||
variable which is typically given to "make install", for makefiles
|
||||
which support staging directories).
|
||||
|
||||
|
|
@ -446,12 +522,12 @@ Package
|
|||
|
||||
(Package) unpacking directory
|
||||
|
||||
(Packages) root directory
|
||||
Layout
|
||||
|
||||
(Package) installation directory
|
||||
(Abstract) location
|
||||
|
||||
Package loading script
|
||||
|
||||
* Version
|
||||
|
||||
$Id: proposal.txt,v 1.1 2003/12/14 12:14:21 michel-schinz Exp $
|
||||
$Id: proposal.txt,v 1.2 2003/12/16 22:16:43 michel-schinz Exp $
|
||||
|
|
|
|||
Loading…
Reference in New Issue