From 383349a3fadc66f96e152f51ccc55a4f3b034929 Mon Sep 17 00:00:00 2001 From: michel-schinz Date: Sun, 14 Dec 2003 12:14:21 +0000 Subject: [PATCH] - initial version (no layouts yet) --- .gitignore | 28 +++ doc/proposal.txt | 457 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 485 insertions(+) create mode 100644 .gitignore create mode 100644 doc/proposal.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..da8168b --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# CVS default ignores begin +tags +TAGS +.make.state +.nse_depinfo +*~ +\#* +.#* +,* +_$* +*$ +*.old +*.bak +*.BAK +*.orig +*.rej +.del-* +*.a +*.olb +*.o +*.obj +*.so +*.exe +*.Z +*.elc +*.ln +core +# CVS default ignores end diff --git a/doc/proposal.txt b/doc/proposal.txt new file mode 100644 index 0000000..89d9fbc --- /dev/null +++ b/doc/proposal.txt @@ -0,0 +1,457 @@ +In Emacs, read this file in -*- Outline -*- mode. + +* Introduction + +The aim of the following proposal is to define a standard for the +packaging, distribution, installation, use and removal of libraries +for scsh. Such packaged libraries are called "scsh packages" or simply +"packages" below. + +This proposal attempts to cover both libraries containing only Scheme +code and libraries containing additional C code. It does not try to +cover applications written in scsh, which are currently considered to +be outside of its scope. + +** Package identification and naming + +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 (_). Package names are +case-sensitive, but there should not be two packages with names which +differ only by their capitalisation. + +Rationale: + + This restriction on package names ensures that they can be used to + name directories on current operating systems. + +Several versions of a given package can exist. A version is identified +by a sequence of non-negative integers. Versions are ordered +lexicographically. + +A version has a printed representation which is obtained by separating +(the printed representation of) its components by dots. For example, +the printed representation of a version composed of the integer 1 +followed by the integer 2 is the string "1.2". Below, versions are +usually represented using their printed representation for simplicity, +but it is important to keep in mind that versions are sequences of +integers, not strings. + +A specific version of a package is therefore identified by a name and +a version. The full name of a version of a package is obtained by +concatenating: + + - the name of the package, + + - a hyphen (-), + + - the printed representation of the version. + +In what follows, the term "package" is often used to designate a +specific version of a package, but this should be clear from the +context. + +* Distribution of packages + +Packages are distributed in TAR archives, which can optionally be +compressed by GZIP or BZIP2. + +The name of the archive is composed by appending: + + - the full name of the package, + + - the string ".tar" indicating that it's a TAR archive, + + - either the string ".gz" if the archive is compressed using GZIP, + or the string ".bz2" if the archive is compressed using BZIP2, or + nothing if the archive is not compressed. + +** 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 package unpacking directory. All the files belonging to the +package are stored below it. + +The unpacking directory contains at least the following files: + + - install-pkg + a script performing the installation of the package, + + - README + a textual file containing a short description of the package, + + - COPYING + a textual file containing the license of the package. + +* Downloading and installation of packages + +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. + +Rationale: + +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. + +** Root directory layout + +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. + +A package root directory contains exactly two sub-directories, and +nothing else. These directories are called "installed" and "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. + +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. + +Example: + +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: + +/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 + +** Package directory layout + +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. + + / + + Directory containing the shared libraries for . + + doc/ + + Directory containing the documentation of the package, possibly in + different formats. + + html/ + + Directory containing the HTML documentation of the package, if + any; this directory should at least contain one file called + "index.html" serving as an entry point to the documentation. + + pdf/ + + Directory containing the PDF documentation of the package, if + any; this directory should contain at least one file called + ".pdf" where "" is the name of the package. + + ps/ + + Directory containing the PostScript documentation of the + package, if any; this directory should contain at least one file + called ".ps" where "" is the name of the + package. + +** File permissions + +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: + + --dry-run or -n + + Print what actions would be performed to install the package, but + do not perform them. + + --inactive or -i + + Do not activate package after installing it. + +** Creating images + +TODO (my current idea is to add support to install-lib to easily + create an image containing the package being installed, and + maybe some structures opened. Then, at install time, users could + say that they want an image to be created, and the install + script would do that). + +* Using packages + +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. + +To load this file, one typically uses scsh's "-lel" option along with +a properly defined SCSH_LIB_DIRS environment variable. + +Scsh has a list of directories, called the library directories, in +which it looks for files to load when the options -ll or -lel are +used. This list can be given a default value during scsh's +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 + +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: + + -lel foo/load.scm + +* Writing packages + +Once the Scheme and/or C code for a package has been written, the last +step in turning it into a standard package as defined by this proposal +is to write the installation script. + +This script could be written fully by the package author, but in order +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 + + 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 + + Scheme 48 interface and structure definitions for the installation + library. + +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), + + - load the package definition file, a (Scheme) file called + "pkg-def.scm", which is supplied by the package author and which + contains the installation procedure for the package, + + - install the package which was defined in the previous step. + +It is actually possible to define several packages in "pkg-def.scm", +and all will be installed. It should not be often useful, though. + +The main job of the package author is therefore to write the package +definition file, "pkg-def.scm". + +This file is mostly composed of a package definition statement, which +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 ...) (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. + +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 [] []) + + 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. + + 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 [] []) + + Like install-file but for several files, which are specified as a + list. + +(install-directory [] []) + + 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. + + Notice that DIR will be installed as a sub-directory of TARGET-DIR. + +(install-directories [] []) + + Install several directories in one go. + +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"))) + +With such a definition, invoking the installation script with +"/usr/local/lib/scsh/modules" as package root would have the +following effects: + +1. The package directory + + /usr/local/lib/scsh/modules/installed/my_package/1.2 + + would be created. + +2. File "load.scm" would be copied to this directory. + +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 + + The same would happen for the contents of directory "doc". + +4. The package would be activated by creating a symbolic link with + name + + /usr/local/lib/scsh/modules/active/my_package + + pointing to + + ../installed/my_package/1.2 + +** Packages containing C code (for shared libraries) + +Packages containing C code are more challenging to write, since all +the problems related to C's portability and incompatibilities between +the APIs of the various platforms have to be accounted for. +Fortunately, the GNU Autoconf system simplifies the management of +these problems, and authors of scsh packages containing C code are +strongly encouraged to use it. + +Integrating Autoconf into the installation procedure should not be a +major problem thanks to scsh's ability to run separate programs. + +* Packaging packages + +Most important Unix systems today have one (or several) package +management systems which ease the installation of packages on a +system. In order to avoid confusion between these packages and the +scsh packages discussed above, they will be called "system packages" +in what follows. + +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. + +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. + +(The --dest-root option plays the same role as the DEST_DIR +variable which is typically given to "make install", for makefiles +which support staging directories). + +* Glossary + +TODO define the following terms + +Version + +Target machine + +Package + +(Package) unpacking directory + +(Packages) root directory + +(Package) installation directory + +Package loading script + +* Version + +$Id: proposal.txt,v 1.1 2003/12/14 12:14:21 michel-schinz Exp $