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.4".
: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.4"):source
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"))).
:git
The git directive specifies a requirement that must be satisfied by a git repository hosted at an arbitrary location. Unless specified otherwise, every explicitly defined system (and their dependencies) are included in the bundle.
(name &key url branch commit tag systems)name
must be a string, unique in the file.
:url
must be a string, the url of 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.
: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