Commit 01ec453c authored by Eric Timmons's avatar Eric Timmons

Update documentation based on Andrew's comments

parent 9dd49859
Pipeline #854 passed with stage
in 10 minutes and 53 seconds
......@@ -14,17 +14,23 @@ is still a little rough around the edges and it may accidentally eat your files.
It consists of two major pieces. First is a standalone program that is
responsible for all the heavy lifting of fetching and unpacking releases in
the correct place and managing project specific environments. This piece is
generally referred to as CLPM, the CLPM core, or =clpm=. The second is a small
client library written in portable Common Lisp that interfaces with ASDF and
calls CLPM as necessary to find and install missing systems. This piece is
generally referred to as the CLPM client or =clpm-client=.
generally referred to as CLPM, the CLPM core, or =clpm= and is distributed as
a precompiled image using SBCL (but it is possible to compile it from
source). The second is a small client library written in portable Common Lisp
that interfaces with ASDF and calls CLPM as necessary to find and install
missing systems. This piece is generally referred to as the CLPM client or
=clpm-client= and is meant to be loaded into development images.
To contact the developers, send email to and/or join
clpm-devel@common-lisp.net
[[https://mailman.common-lisp.net/listinfo/clpm-devel]].
* Project Goals
CLPM is far from the only package manager available for Common Lisp[fn:1], but
it makes very different assumptions and design choices than the other
available solutions. We try to describe our high level goals and how they
affect our design decisions in this section.
available solutions. In this section we describe our high level goals and how
they affect our design decisions.
+ Minimize footprint in development Lisp image :: Ultimately, dependency
management should not be a large part of developing a library or
......@@ -33,7 +39,7 @@ is still a little rough around the edges and it may accidentally eat your files.
(nontrivial amounts of) code necessary for downloading libraries, resolving
their dependencies, unpacking them, and installing them ever be present in
your development Lisp image? This drives CLPM's separation into the core and
client. Additionally, some Lisps (I'm looking at you, SBCL) have a large
the client. Additionally, some Lisps (I'm looking at you, SBCL) have a large
memory footprint and this helps keep that down.
+ Use existing libraries where possible :: Because the CLPM core never needs
to be loaded into a development image, there are no issues with version
......@@ -41,7 +47,7 @@ is still a little rough around the edges and it may accidentally eat your files.
and the code being developed. This means that existing libraries can be
leveraged where it makes sense and we don't need to reinvent the wheel.
+ Support cleanup on image dump :: Many Common Lisp implementations allow you
to deliver programs by dumping an in memory image to file. For most programs
to deliver programs by dumping an in-memory image to file. For most programs
generated there is no need to have a bundled package manager. Therefore,
CLPM provides an option to remove the client from the image when it is
dumped (using UIOP provided functions).
......@@ -56,14 +62,14 @@ is still a little rough around the edges and it may accidentally eat your files.
dependencies.
+ Support multiple package sources :: At first, CLPM will support only
Quicklisp-style distributions as a package source/repository. But we
envision adding support for new sources, such as a new work in progress
repository geared toward projects that maintain their own release schedule.
envision adding support for new sources, preferably including one that
stores the upstream repos for each project.
* Installing
CLPM is distributed in both source and binary form. Additionally, the binaries
are distributed in both dynamic and statically linked forms (note: the
binaries are built with SBCL which does not support statically linking against
are distributed in both dynamically and statically linked forms (note: the
binaries are built with SBCL, which does not support statically linking against
the C library[fn:3], so you need to get the one that matches your OS's libc
(most likely the =gnu= variant)).
......@@ -78,8 +84,8 @@ is still a little rough around the edges and it may accidentally eat your files.
+ sqlite :: Needed if compiling from source or using the dynamically linked
version.
After installing CLPM, it is recommended you also install the CLPM client (see
[[file:doc/client.org][client.org]]), but it is not needed for the quickstart.
After installing CLPM core, it is recommended you also install the CLPM client
(see [[file:doc/client.org][client.org]]), but it is not needed for the quickstart.
** Prebuilt binaries
To install CLPM in binary form, download the appropriate file from
......@@ -110,11 +116,12 @@ is still a little rough around the edges and it may accidentally eat your files.
with GPG key =0x10327DE761AB977333B1AD7629932AC49F3044CE=.
After downloading the binary and validating the SHA512 sum, make sure the
file is executable and save it as =clpm= somewhere on your PATH.
file is executable, and save it as =clpm= (or =clpm.exe=) somewhere on your
PATH.
** Source install
The next easiest way to install CLPM is to install SBCL, clone the CLPM
sources (including the git submodules!), and link the [[file:scripts/clpm-live][clpm-live]] script as
sources (including the git submodules!), and symlink the [[file:scripts/clpm-live][clpm-live]] script as
=clpm= somewhere on your PATH. Alternatively, you can build a dynamically or
statically linked executable by running one of the following:
......@@ -204,5 +211,5 @@ know!
[fn:1] See, for example: [[https://www.quicklisp.org/beta/][Quicklisp]], [[https://github.com/fukamachi/qlot/][Qlot]], and [[https://github.com/CodyReichert/qi][Qi]].
[fn:2] Using the archive library for a full Common Lisp solution is on the
[fn:2] Using the archive CL library for a full Common Lisp solution is on the
roadmap, but it needs a decent amount of work.
......@@ -3,10 +3,9 @@
#+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 - i.e.,
helping handle where the rubber meets the road. While ASDF famously does not
allow developers to specify upper bounds on dependency versions (only lower
bounds) [fn:1] [fn:2], CLPM's bundle capability allows exactly that, in addition
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!).
......@@ -26,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.1".
*** ~:api-version~
......@@ -40,8 +39,9 @@ with zero configuration or helpers needed (other than ASDF, of course).
*** ~:source~
Each clpmfile must include at least one source directive. This tells CLPM
which sources it is allowed to search for dependencies in. The first
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 standard
quicklisp distribution, you can write:
......@@ -53,8 +53,6 @@ with zero configuration or helpers needed (other than ASDF, of course).
:force-https t)
#+end_src
All source directives must come immediately after the api-version directive.
*** ~:git~
The git directive specifies a requirement that must be satisfied by a git
......@@ -74,7 +72,7 @@ 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]
*** ~:gitlab~
......@@ -132,26 +130,27 @@ with zero configuration or helpers needed (other than ASDF, of course).
* Commands
** =clpm bundle install=
If the lock file exists, load it and ensure that all releases included in the
bundle are installed locally. If the lock file does not exist, create it and
then ensure all releases are installed.
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=) in an environment where ASDF
will have access to all systems included in the bundle with no extra
configuration. Requires the lock file to exist.
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 passed on to the new process, additionally the
All environment variables are present in the new process, additionally the
following environment variables are set:
+ =CL_SOURCE_REGISTRY= :: Set to contain the parent folders of every .asd
file in the bundle.
+ =CLPM_BUNDLE_BIN_PATH= :: Set to the path to the clpm executable.
+ =CLPM_BUNDLE_BIN_PATH= :: Set to the path to the clpm executable. Used by
the client.
+ =CLPM_BUNDLE_CLPMFILE= :: Set to the path to the clpmfile that defines the
bundle.
bundle. Used by the client.
+ =CLPM_BUNDLE_CLPMFILE_LOCK= :: Set to the path to the clpmfile.lock that
defines the bundle.
defines the bundle. Used by the client.
** =clpm bundle update=
......@@ -177,11 +176,7 @@ with zero configuration or helpers needed (other than ASDF, of course).
[fn:1] https://bugs.launchpad.net/asdf/+bug/1183179
[fn:2] I personally didn't like this restriction at first, but upon much
reflection realized that Faré's argument made a lot of sense. That realization
was one of the impetuses to designing the bundle capabilities of CLPM.
[fn:3] Only the top level system of a package-inferred-system is considered to
[fn:2] Only the top level system of a package-inferred-system is considered to
be explicitly defined. If you require dependencies of subsystems that the top
level system does not depend on to be satisfied, you must list those systems
explicitly.
......@@ -3,14 +3,15 @@
#+EMAIL: clpm-devel@common-lisp.net
While CLPM can be used without the client, installing and using the client makes
Common Lisp coding a more interactive and fun experience. The CLPM Client can be
loaded into a Lisp image and integrates into ASDF to seamlessly install missing
Common Lisp coding a more interactive and fun experience. The CLPM client can be
loaded into a Lisp image and integrates with ASDF to seamlessly install missing
systems a la the Quicklisp client.
* Installing
To install the CLPM Client, run the following. It will additionally prompt if
you want to add the client to your ASDF search path (highly recommended).
To install the CLPM Client, run the following in your favorite terminal
emulator. It will additionally prompt if you want to add the client to your
ASDF search path (highly recommended).
#+begin_src shell
clpm client
......
......@@ -8,11 +8,11 @@ default order of directories searched is first the =common-lisp/clpm= folder of
the user's XDG config directory (typically =$HOME/.confg/=), then in the system
config folder (typically =/etc/=). The order can be changed with the
=CLPM_CONFIG_DIRS= environment variable. If specified, it must be a list of
directories separated by your OS's conventional directory separator. The default
search locations will be spliced into the list if any entry in the list is
empty.
directories separated by your OS's conventional directory separator. If any
entry in the list is empty. The default search locations will be spliced into
the list.
The contents of this file must be a single list that starts with ~clpm-config~
The contents of =clpm.conf= must be a single list that starts with ~clpm-config~
and the rest must be a plist. Each key in the plist names either a value or a
section. If it names a section, the value must be another plist. If it names a
value, the value is read according to the rules for that value.
......
......@@ -6,15 +6,15 @@ This document specifies what files on your computer CLPM will touch and why.
* Cache
CLPM stores its cache in the =common-lisp/clpm= subfolder of your user XDG
cache directory (typically =~/.cache/=). The location can be overridden using
the =CLPM_CACHE_DIR= environment variable.
CLPM stores its cache in the =common-lisp/clpm= subfolder of your user
XDG[fn:1] cache directory (typically =~/.cache/=). The location can be
overridden using the =CLPM_CACHE_DIR= environment variable.
In the cache folder, CLPM stores tarballs from sources, git repos, fasls
generated when grovelling for system info and dependencies, etc.
generated when groveling for system info and dependencies, etc.
Generally, that cache can be deleted at any time (except when an instance of
CLPM is running) and CLPM will redownload or generate files as necessary.
CLPM is running), and CLPM will redownload or generate files as necessary.
* Data
......@@ -27,11 +27,15 @@ This document specifies what files on your computer CLPM will touch and why.
To enable ASDF to find installed systems outside of bundles, CLPM writes the
following files to your user XDG config folder (typically =~/.config/=):
+ =common-lisp/source-registry.conf.d/20-clpm-client.conf= :: Written by =clpm
client= to allow ASDF to find the CLPM client.
+ =common-lisp/source-registry.conf.d/20-clpm-client.conf= :: Written by =clpm client=
to allow ASDF to find the CLPM client.
+ =common-lisp/source-registry.conf.d/50-clpm.conf= :: Written to any time a
new library is installed for your user, pointing ASDF to where it is
installed.
+ =common-lisp/source-registry.conf.d/50-clpm.conf.meta= :: Written to any
time a new library is installed for your user. Contains metadata telling
CLPM which entries in =50-clpm.conf= belong to which projects.
* Footnotes
[fn:1] https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
Markdown is supported
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