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) [fn: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).
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”.
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")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")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:tagto 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"))).
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"))).
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.
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.
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.
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.
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.
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.
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.
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-translationsin the(:bundle)config table. CL_SOURCE_REGISTRY- Set to contain the parent folders of every .asd file in the bundle.
Update the lock file to point to the latest versions available that satisfy
the constraints in the clpmfile.