gauche.package - Package metainformation ¶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.
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.
Note that package.scm may be referenced directly from its source repository. Gauche packages are uniquely identified by the repository URL, and its package.scm file is the definite source of metainformation of the package.
Defines a package name. Name must be a symbol. It is followed by a keyword-value list. The following keywords are recognized.
repository(string) A repository URL of the package. This is used as a unique identifier of the package when the package is published.
version(String) The version of the package, e.g. "1.0".
description(String) The description of the pacakge. The first line (up to the first newline character) should be the one-line summary of the package.
require(List) 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(List) A list of module names in symbols, that this package provides.
authors(List) A list of name and contact info of the authors of this package.
maintainers(List) A list of name and contact info of the maintainers of this package,
if they differ from the authors.
licenses(List) A list of licenses in strings.
homepage(String) A homepage URL of the package, if any.
superseded-by(String) 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.
{gauche.package}
An object to handle package descriptions programatically.
It has the following slots.
<gauche-package-description>: name ¶The name of the package, a string.
<gauche-package-description>: repository ¶An URL to the repository of this package, a string. A package is primarily identified by the repository URL.
<gauche-package-description>: version ¶The version of the package, a string, e.g. "1.0".
<gauche-package-description>: description ¶The description of the package, a string. Up to the first newline character may be used as a short summary.
<gauche-package-description>: require ¶A list of (package-name version-spec), to specify
the other packages this package requires.
<gauche-package-description>: providing-modules ¶A list of module names (symbols) that this package provides.
<gauche-package-description>: authors ¶A list of author’s name and contact info.
<gauche-package-description>: maintainers ¶A list of maintainer’s name and contact info, if it differs from
authors.
<gauche-package-description>: licenses ¶A list of licenses. E.g. "BSD",
"MIT", "GPL2", "GPL3", "Apache2" etc.
<gauche-package-description>: homepage ¶An URL to the homepage of this package, if any.
<gauche-package-description>: superseded-by ¶If not #f, the value is a repository URL of the successor
of this package.
When development of a package is stopped and someone else
succeeded the further development, the original package specifies
the successor here to show the succession “official”.
<gauche-package-description>: gauche-version ¶Gauche version with which this module is installed.
<gauche-package-description>: configure ¶A command-line string keeping how configure script was run
to build and install this package.
{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.
To find out installed gpd file(s), you can use
find-gauche-package-description below.
{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.
{gauche.package}
Creates and returns a new instance of <gauche-package-description>,
the slots of which is initialized with the given keyword arguments.
{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.
{gauche.package}
Try to find a package description of name (string)
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.