A Lispy Map describes a repository of Lispy library archives and their dependencies. Maps may be “sewn” together or merged by the Lispy user when they set lispy:*lispy-map-urls* in their ~/.lispy.lisp configuration file.
A map is represented by a list of map entries where each entry is represented by a plist. An entry consists of the following keyword properties:
| Name | Required | Description |
|---|---|---|
| :name | Required | A keyword which identifies the entry. This does not have to be unqiue within one map, but the last listed entry will take precedence. The mapping order in lispy:*lispy-map-urls* dictates which entry takes precedence in the case where the same name appears in more than one map. This is useful for overriding libraries. |
| :homepage | Optional | The URL of the author or project home page. If a home page does not exist, this should be a URL which most easilly allows someone to find the original download location of the library. This property is used in the construction of user visible library lists. |
| :description | Optional | A description of the library. This property is used in the construction of user visible library lists. |
| :versions | Required | A list of one ore more version entries. |
A version entry describes a version of the library. As libraries change over time, so do their dependencies and ASDF locations. A version entry encapsulates those changes. A version entry consists of the following keyword properties:
| Name | Required | Description |
|---|---|---|
| :our-version | Required | An integer value which abstracts the library version. To avoid complicated version string parsing logic, we use :our-version in a simple integer comparison to determine which is the latter of two versions of a library. |
| :version | Required | The actual version string. This is the upstream author's idea of the library version. It is used when presenting a version to the user. |
| :source | Required | The library source archive name. |
| :md5sum | Required | The MD5 check sum of the source archive represented by a lower-case, hexidecimal-encoded string. This is used to verify the integrity of the downloaded source. It is used indirectly (via the GPG signature of the map as a whole) to determine if tampering has taken place. |
| :root | Required | The directory the archive will unpack into represented by a Lisp pathname. This is also used as the value of :asdf-paths in the case that it is not given in a version entry. |
| :asdf-paths | Optional | A list of Lisp pathnames into the unpacked archive where ASDF files should be found. These paths are added to asdf:*asdf-central-registry* by Lispy. If this property is not given, then the :root property is used. |
| :dependencies | Optional | A list of archive names this version of the library depends on. You cannot depend on a specific version of another library, so the map must be updated so that the latest dependencies make sense overall. Note: this dependency list frequently matches the :depends-on list within a similarly named ASDF file, however this is not always the case — the :dependencies list must be thought of as the more abstract archive dependency list. |
The typical case of a library containing ASDF file which has been updated over time to the lastest version.
(:name :flexi-streams
:homepage "http://weitz.de/flexi-streams/"
:description "FLEXI-STREAMS implements \"virtual\" bivalent streams
that can be layered atop real binary or bivalent streams and that
can be used to read and write character data in various single-
or multi-octet encodings which can be changed on the fly. It also
supplies in-memory binary streams which are similar to string streams."
:versions ((:our-version 1
:version "0.13.1"
:source "flexi-streams-0.13.1.tar.gz"
:md5sum "20af2050f47b971f1e96c3652028a26f"
:root #p"flexi-streams-0.13.1/"
:dependencies (:trivial-gray-streams))
(:our-version 2
:version "0.14.0"
:source "flexi-streams-0.14.0.tar.gz"
:md5sum "a116ed32c59b08f6c926d92752524ded"
:root #p"flexi-streams-0.14.0/"
:dependencies (:trivial-gray-streams))))
A case where more than one entry is contained in :asdf-paths. CL-IRC comes with some interesting tests, so the :asdf-paths includes the pathname which contains the test ASDF file. Note that the :rt dependency is given, which is only used by the CL-IRC test ASDF file.
(:name :cl-irc
:homepage "http://common-lisp.net/project/cl-irc/"
:description "cl-irc is a Common Lisp IRC client library that
features (partial) DCC, CTCP and all relevant commands from the
IRC RFCs (RFC2810, RFC2811 and RFC2812)."
:versions ((:our-version 0
:version "0.8.1"
:source "cl-irc_0.8.1.tar.gz"
:md5sum "436ac1499e8af4760096713e9fb681c8"
:root #p"cl-irc-0.8.1/"
:asdf-paths (#p"cl-irc-0.8.1/" #p"cl-irc-0.8.1/test/")
:dependencies (:usocket :split-sequence :flexi-streams :rt))))
Lispy has a fairly rigid repository structure. A map file can be contained anywhere, but it must include a sub-directory distfiles/ where the source archives are contained. For example, http://common-lisp.net/project/lispy/repository/map.lisp-expr will refer to source archives in http://common-lisp.net/project/lispy/repository/distfiles/.