Commit 8a0bf51d authored by Eric Timmons's avatar Eric Timmons
Browse files

Update bundle documentation

parent fa01adbe
......@@ -2,13 +2,13 @@
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
This file describes the "bundle" capabilities of CLPM. Bundles are meant to ease
the problems of repeatable deployment and testing in the CL world. 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!).
This file describes the "bundle" capabilities of CLPM. 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
......@@ -25,7 +25,7 @@ with zero configuration or helpers needed (other than ASDF, of course).
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.1".
describes version "0.2".
*** ~:api-version~
......@@ -34,7 +34,7 @@ with zero configuration or helpers needed (other than ASDF, of course).
file is described in. Example:
#+begin_src common-lisp
(:api-version "0.1")
(:api-version "0.2")
#+end_src
*** ~:source~
......@@ -53,26 +53,35 @@ with zero configuration or helpers needed (other than ASDF, of course).
:force-https t)
#+end_src
*** ~:git~
*** ~:project~
The git directive specifies a requirement that must be satisfied by a git
repository. Unless specified otherwise, every explicitly defined system (and
their dependencies) are included in the bundle.
The project directive declares a dependency on an entire project.
#+begin_src common-lisp
(name &key repo branch commit tag systems)
(name &key vcs systems source)
#+end_src
+ ~name~ :: must be a string, unique in the file.
+ ~:repo~ :: is a string naming the URL to the repository. Must include the
scheme and full path.
+ ~: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.[fn:2]
+ ~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 explicitly defined systems
are required.
*** ~:system~
The system directive declares a dependency on a specific system.
#+begin_src common-lisp
(name &key source)
#+end_src
+ ~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.
*** ~:gitlab~
......@@ -94,7 +103,8 @@ with zero configuration or helpers needed (other than ASDF, of course).
+ ~: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.[fn:3]
all explicitly defined systems are required.[fn:2]
*** ~:asd~
This directive states that the specified asd file should be included in the
......@@ -108,7 +118,7 @@ with zero configuration or helpers needed (other than ASDF, of course).
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.[fn:3]
asd file are required and have their dependencies satisfied.[fn:2]
** clpmfile.lock
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment