CLPM Bundles

This file describes the "bundle" capabilities of CLPM. Bundles are anonymous, project specific contexts that can be included in source repositories.

Bundles are meant to ease the problems of creating repeatable development, deployment, and testing environments. While ASDF does not allow developers to specify upper bounds on dependency versions (only lower bounds) [1], CLPM's bundle capability allows exactly that, in addition to specifying that some dependency should be satisfied by some unreleased version directly from source control (great for developing projects in multiple repos simultaneously!).

A CLPM bundle is a collection of systems locked at specific versions. A bundle is fully defined by a clpmfile.lock file, which is itself created from a clpmfile file. Once a lock file is generated, the bundle commands allow you to perform tasks such as running Lisp processes that can load systems in the bundle with zero configuration or helpers needed (other than ASDF, of course).

Files

clpmfile

A clpmfile describes what projects or systems a user wants to place in a bundle and any constraints she has on the versions of those objects. It is a file, typically located at the root of a source code repository, that consists of a series of directives where each directive is a list starting with a keyword. The directives are described below. Additionally, the first directive in the file must be the :api-version directive. This document describes version "0.3".

:api-version

This directive must be the first to appear in the file. It consists of one argument that must be a string naming the clpmfile version the rest of the file is described in. Example:

(:api-version "0.3")

:source

Each clpmfile must include at least one source directive. All source directives must come immediately after the api-version directive. This tells CLPM which sources it is allowed to search for dependencies in. The first argument to this directive is the name of the source as a string. The remainder is a plist describing the source. For example, to use the primary quicklisp distribution, you can write:

(:source "quicklisp"
 :type :quicklisp
 :url "https://beta.quicklisp.org/dist/quicklisp.txt")

:project

The project directive declares a dependency on an entire project.

(name &key vcs systems source version)
  • name
    must be a string, naming the project.
  • :source
    If provided, names a source that the system must be located in.
  • :vcs
    If provided, must be a plist naming the :branch, :commit, or :tag to use when checking out the project from version control.
  • :systems
    If provided, must be a list of strings naming the systems to be required in the bundle. Otherwise all systems are required.
  • :version
    If provided, must be a version specifier. Can either be a string (in which case it is parsed as if by clpm install), a single version specifier (such as (= "1.2")), or a list of version specifiers (such as ((>= "1.1") (< "2"))).

:system

The system directive declares a dependency on a specific system.

(name &key source version)
  • name
    must be a string, naming a system provided by one of the specified sources.
  • :source
    If provided, names a source that the system must be located in.
  • :version
    If provided, must be a version specifier. Can either be a string (in which case it is parsed as if by clpm install), a single version specifier (such as (= "1.2")), or a list of version specifiers (such as ((>= "1.1") (< "2"))).

:github

The github directive specifies a requirement that must be satisfied by a git repository hosted on a github server. Unless specified otherwise, every explicitly defined system (and their dependencies) are included in the bundle.

(name &key (host "github.com") path branch commit tag systems)
  • name
    must be a string, unique in the file.
  • :host
    is the hostname of the github server. Defaults to github.com.
  • :path
    is a string naming the path to the repository.
  • :branch
    If specified, must be a string naming the branch to use. If none of branch, commit, or tag are specified, the branch defaults to the default branch from the server.
  • :commit
    If specified, must be a string naming the commit to use.
  • :tag
    If specified, must be a string naming the tag to use.
  • :systems
    A list naming the systems to require in the bundle. If NIL, all systems are required.

:gitlab

The gitlab directive specifies a requirement that must be satisfied by a git repository hosted on a gitlab server. Unless specified otherwise, every explicitly defined system (and their dependencies) are included in the bundle.

(name &key (host "gitlab.com") path branch commit tag systems)
  • name
    must be a string, unique in the file.
  • :host
    is the hostname of the gitlab server. Defaults to gitlab.com.
  • :path
    is a string naming the path to the repository.
  • :branch
    If specified, must be a string naming the branch to use. If none of branch, commit, or tag are specified, the branch defaults to the default branch from the server.
  • :commit
    If specified, must be a string naming the commit to use.
  • :tag
    If specified, must be a string naming the tag to use.
  • :systems
    A list naming the systems to require in the bundle. If NIL, all explicitly defined systems are required.

:asd

This directive states that the specified asd file should be included in the bundle. The arguments it accepts are:

(asd-path &key systems)
  • asd-path
    Must be a string providing the path to the asd file, relative to the clpmfile.
  • systems
    What systems defined by the ASD file should be included. Must be a list of strings. If NIL, then all systems explicitly defined in the asd file are required and have their dependencies satisfied.

clpmfile.lock

The lock file defines all releases included in the bundle. This consists of every top level requirement specified in the clpmfile and their dependencies. When the dependencies are resolved, any system fetched from source control is assumed to satisfy any requirements placed on it. No formal commitment to syntax for this file is guaranteed yet.

Configuration

Every bundle command reads the file .clpm/bundle.conf (if it exists, relative to the clpmfile) and merges the configuration defined in that file into CLPM's central config. Currently, all configuration sections are merged, in a future version a whitelist of configuration options will be defined.

Commands

clpm bundle install

If the lock file does not exist, create it and then ensure all releases are installed. If the lock file exists, load it and ensure that all releases included in the bundle are installed locally.

clpm bundle exec

Execute the specified command (following exec) where environment variables are set such that ASDF will have access to all systems included in the bundle with no extra configuration. Requires the lock file to exist.

All environment variables are present in the new process, additionally the following environment variables are set:

  • ASDF_OUTPUT_TRANSLATIONS
    If CLPM is configured to manage the output translations for bundles. See :output-translations in the (:bundle) config table.
  • CL_SOURCE_REGISTRY
    Set to contain the parent folders of every .asd file in the bundle.

clpm bundle update

Update the lock file to point to the latest versions available that satisfy the constraints in the clpmfile.

Footnotes

  1. https://bugs.launchpad.net/asdf/+bug/1183179