9.23 gauche.package - Package metainformation

Module: gauche.package ¶

Gauche manages extra libraries and extension modules as packages.

Each package source tree has package.scm on top directory, which contains define-gauche-package form that provides metainformation about the package—the package name, version, author, dependencies, etc.

When the package is installed, the standard installation process copies that information, with additional information such as the version of Gauche used to build the package, into .packages subdirectory of the library installation path, with the name PACKAGENAME.gpd, where PACKAGENAME is the name of the package.

We collectively call package.scm and *.gpd as package description file.

This module provides utility procedures to read and write package description files, and search installed *.gpd files.

package.scm

A package file, package.scm, must contain one package definition in the following form. It is not evaluated; it is read as a literal data.

Package definition: define-gauche-package name key-value-list … ¶

Defines a package name. It is followed by a keyword-value list. The following keywords are recognized.

repository

A repository URL of the package. This is used as a unique identifier of the package.

version

The version of the package, in a string, e.g. "1.0".

description

The description of the pacakge, in a string. The first line (up to the first newline character) should be the one-line summary of the package.

require

A list of requirements. Each requirement is (<package-name> <version-spec>), where <package-name> is a string package name, and <version-spec> determines the accepable versions of the package. See gauche.version - Comparing version numbers, for the details of <version-spec>.

providing-modules

A list of module names in symbols, that this package provides.

authors

A list of name and contact info of the authors of this package.

maintainers

A list of name and contact info of the maintainers of this package, if they differ from the authors.

licenses

A list of licenses.

homepage

A homepage URL of the package, if any.

superseded-by

If the developers stop maintaining this package, but another developer wants to continue development with a forked repository, the original developer can officially appoint the successor by specifying the new repository URL here.

configure script and *.gpd file generation

If you use configure script based on gauche.configure (see gauche.configure - Generating build files), a Gauche package description file (*.gpd) is created with it. The gpd file contains information from package.scm, plus the information on the installaion platform gathered by configure.

The generated gpd file is installed with the package itself, and will be used by gauche-package command, as well as retrieved by the following utility APIs.

Utility procedures

Function: <gauche-package-description> ¶

{gauche.package} An object to handle package descriptions programatically.

Instance Variable of <gauche-package-description>: name ¶

The name of the package, a string

Instance Variable of <gauche-package-description>: repository ¶

An URL to the repository of this package.

Instance Variable of <gauche-package-description>: version ¶

The version of the package, a string, e.g. "1.0".

Instance Variable of <gauche-package-description>: description ¶

The description of the package. Up to the first newline character may be used as a short summary.

Instance Variable of <gauche-package-description>: require ¶

A list of (package-name version-spec), to specify the other packages this package requires.

Instance Variable of <gauche-package-description>: providing-modules ¶

A list of module names (symbols) that this package provides.

Instance Variable of <gauche-package-description>: authors ¶

A list of author’s name and contact info.

Instance Variable of <gauche-package-description>: maintainers ¶

A list of maintainer’s name and contact info, if it differs from authors.

Instance Variable of <gauche-package-description>: licenses ¶

A list of licenses.

Instance Variable of <gauche-package-description>: homepage ¶

An URL to the homepage of this package.

Instance Variable of <gauche-package-description>: superseded-by ¶

If not #f, the value is a repository URL of the successor of this package.

Instance Variable of <gauche-package-description>: gauche-version ¶

Gauche version with which this module is installed.

Instance Variable of <gauche-package-description>: configure ¶

A command-line string keeping how configure script was run to build and install this package.

Function: path->gauche-package-description filename ¶

{gauche.package} The named file must be a gpd file. This reads the file and returns an instance of <gauche-package-description>.

An error is thrown if filename can’t be read, or doesn’t have a proper define-gauche-package form.

Function: write-gauche-package-description description :optional oport ¶

{gauche.package} Write out the content of <gauche-package-description> instance, description as a define-gauche-package form, to an output port oport. If oport is omitted, current output port is used.

Function: make-gauche-package-description name :key version description require maintainers authors licenses homepage repository gauche-version configure providing-modules ¶

{gauche.package} Creates and returns a new instance of <gauche-package-description>, the slots of which is initialized with the given keyword arguments.

Function: gauche-package-description-paths :key all-versions ¶

{gauche.package} Gather all the gpd file paths installed in the standard location on the system. By default, it collects packages installed in *load-path*. If you give a true value to all-version, it attempts to collect packages installed for other versions of Gauche as well.

Function: find-gauche-package-description name :key all-versions ¶

{gauche.package} Try to find a package description of name installed in the standard location, and returns an instance of <gauche-package-description> if found. Returns #f if the named package isn’t found.

By default, it collects packages installed in *load-path*. If you give a true value to all-version, it attempts to collect packages installed for other versions of Gauche as well.