Commit 5a1ec599 authored by Eric Timmons's avatar Eric Timmons
Browse files

Documentation cleanup and defaults tweaks

CLPM is currently a one-man effort. Don't give the impression there are a ton
of developers in the wings :P
parent a97ccc3e
#+TITLE: Common Lisp Package Manager - CLPM
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: email:t toc:1 num:nil
......@@ -90,16 +90,17 @@ files.
* Quickstart
Now that you have CLPM installed, this section walks you through how to set
it up as a Quicklisp alternative.
it up, using the packages provided by the primary Quicklisp distribution.
First, configure CLPM to use a mirror of the primary Quicklisp distribution
as a source for packages [fn:1]. Create a file called
=~/.config/clpm/sources.conf= with the following contents:
First, configure CLPM to use the primary Quicklisp distribution as a source
for packages. Create a file called =~/.config/clpm/sources.conf= (or
=C:\Users\$USER\AppData\Local\config\clpm\sources.conf= on Windows) with the
following contents:
#+begin_src common-lisp
("quicklisp"
:type :ql-clpi
:url "https://quicklisp.common-lisp-project-index.org/")
:type :quicklisp
:url "https://beta.quicklisp.org/dist/quicklisp.txt")
#+end_src
See [[file:docs/sources.org][sources]] for more details on configuring sources.
......@@ -108,22 +109,37 @@ files.
of the following command in your Lisp's init file (such as =~/.sbclrc=).
#+begin_src shell
clpm client rc --quicklisp-alternative
clpm client rc
#+end_src
Then you can start your favorite Common Lisp implementation and try loading a
system, such as alexandria:
Then you can start your favorite Common Lisp implementation and enter into
the default CLPM context.
#+begin_src common-lisp
(clpm-client:activate-context "default" :activate-asdf-integration t)
#+end_src
When using Quicklisp metadata directly, you need to sync in order to get all
the metadata locally (other types of sources are able to lazily sync). This
step may take a while the first time as it downloads and processes every
version of the distribution.
#+begin_src common-lisp
(clpm-client:sync :sources "quicklisp")
#+end_src
Now you can try loading a system, such as alexandria:
#+begin_src common-lisp
(asdf:load-system :alexandria)
#+end_src
CLPM will see that alexandria is not present locally and automatically
install it before loading it.
CLPM will see that alexandria is not present locally and ask you if you would
like to install it automatically.
* Project Goals
CLPM is far from the only package manager available for Common Lisp[fn:2], but
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. In this section we describe our high level goals and how
they affect our design decisions.
......@@ -143,11 +159,11 @@ files.
drive the quality of code in the community at large higher.
The desire to use existing libraries drives the decision for the CLPM core
and client to be separated. The client has no external dependencies which
allows it to share all the benefits of Quicklisp's model, and the core never
needs to be loaded into a development image, so it can leverage any
dependency that makes sense without impacting the development image in the
slightest.
and client to be separated. The client has no external dependencies outside
of ASDF/UIOP, which allows it to share all the benefits of Quicklisp's
model, and the core never needs to be loaded into a development image, so it
can leverage any dependency that makes sense without impacting the
development image in the slightest.
** Support HTTPS
......@@ -210,11 +226,11 @@ files.
critical mass did buy in, things wouldn't change overnight.
Therefore, CLPM supports both the status quo (a Quicklisp package index
versioned by date) as well as a work in progress package index (working name
versioned by date) as well as a [[https://gitlab.common-lisp.net/clpm/clpi][work in progress package index]] (working name
of CLPI). This new Common Lisp Project Index includes both extra metadata
about projects (such as the upstream repo which can be used to check out
development versions) and requires that systems are versioned in order to be
released.
development versions) as well as information on the ASDF system version
numbers.
* In-depth Documentation
......@@ -229,11 +245,4 @@ files.
* Footnotes
[fn:1] This mirror is generated using the [[https://gitlab.common-lisp.net/clpm/ql-clpi][ql-clpi project]], which stores
information about the projects and releases in a [[https://gitlab.common-lisp.net/clpm/clpi][Common Lisp Project Index]]. A
goal of CLPI is to make it easy to download only the pieces of information
needed to perform the operation at hand, instead of needing to sync all data
about all releases locally. If you wish to not use this mirror, see [[file:docs/sources.org][sources]] for
information on how to use a Quicklisp distribution directly.
[fn:2] See, for example: [[https://www.quicklisp.org/beta/][Quicklisp]], [[https://github.com/fukamachi/qlot/][Qlot]], and [[https://github.com/CodyReichert/qi][Qi]].
[fn:1] See, for example: [[https://www.quicklisp.org/beta/][Quicklisp]], [[https://github.com/fukamachi/qlot/][Qlot]], and [[https://github.com/CodyReichert/qi][Qi]].
......@@ -45,6 +45,7 @@
(asdf:load-asd client-asd-pathname)
(asdf:load-system \"clpm-client\")
(setf (symbol-value (uiop:find-symbol* :*asdf-system-not-found-behavior* :clpm-client)) :install)
(setf (symbol-value (uiop:find-symbol* :*context-diff-approval-method* :clpm-client)) t)
(if (uiop:symbol-call :clpm-client :active-context)
(uiop:symbol-call :clpm-client :activate-asdf-integration)
(uiop:symbol-call :clpm-client :activate-context \"default\" :activate-asdf-integration t))))")
......
#+TITLE: CLPM Bundle
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
......@@ -181,12 +181,6 @@ with zero configuration or helpers needed (other than ASDF, of course).
config table.
+ =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. Used by
the client.
+ =CLPM_BUNDLE_CLPMFILE= :: Set to the path to the clpmfile that defines the
bundle. Used by the client.
+ =CLPM_BUNDLE_CLPMFILE_LOCK= :: Set to the path to the clpmfile.lock that
defines the bundle. Used by the client.
** =clpm bundle update=
......
#+TITLE: CLPM Client
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
......@@ -14,42 +14,37 @@ Note that the clpm-client interface may change at any time before a stable
* clpm-client ASDF System
The client's ASDF system name is =clpm-client=. It is installed with CLPM,
typically in =/usr/local/lib/clpm/src/clpm-client=. In order to use the
client, you must configure ASDF to find this system (see the ASDF manual for
more information on how to do this) or directly load the .asd file using
typically in =/usr/local/lib/clpm/client/=. In order to use the client, you
must configure ASDF to find this system (see the ASDF manual for more
information on how to do this) or directly load the .asd file using
=asdf:load-asd=.
The output of =clpm client rc= prints several ways to load and configure the
client. The default rc configuration provides a function that loads the
client when called. The =--quicklisp-alternative= option can be used to
generate rc file contents that automatically load the client and configure it
to behave similarly to Quicklisp.
client. The default rc configuration loads the client if it is available, but
does not enter any context or activate ASDF integration. The
=--quicklisp-alternative= option can be used to generate rc file contents
that automatically load the client, activates the default context, and
configure it to behave similarly to Quicklisp.
* ASDF Integration
By default, the client does not hook into ASDF unless directed to. In order
to get the benefit of automatically installing systems, enable the ASDF hooks
by running =(clpm-client:activate-clpm-asdf-integration)=
to get the benefit of automatically installing systems, activate a context
and enable the ASDF hooks by running:
#+begin_src common-lisp
(clpm-client:activate-context "default" :activate-asdf-integration t)
#+end_src
* Configuring
The client exports several variables that control its behavior. These
variables are:
+ =*clpm-cleanup-on-dump-p*= :: Defaults to T. If non-NIL, then the client
attempts to clean up after itself on image dumps. This cleanup attempts to
remove all traces of CLPM from various hooks and then deletes all packages
that belong to the client.
+ =*clpm-context*= :: Defaults to ="default"=. A string naming the global
context to use when not inside a bundle.
+ =*clpm-executable*= :: If you installed CLPM at a non-standard path or wish
to execute it with non-standard options, set this variable. It can either
be a string (the path to CLPM) or a list of strings.
+ =*clpm-system-not-found-behavior*= :: Defaults to =:error=. Controls the
behavior of the client when it ASDF integration has been enabled and a
system cannot be found. If =:error=, it signals a condition with several
restarts enabled to let you interactively determine how to proceed. If
=:install= then it tries to install the missing system. If
=:install-with-deps= then it tries to install the missing system and its
dependencies. If NIL, it does nothing (likely resulting in ASDF signaling
an error.
The client exports several variables that control its behavior. Some of these
variables are listed below, each has a doc string describing its current
behavior.
+ =*cleanup-on-dump-p*=
+ =*default-context*=
+ =*clpm-executable*=
+ =*asdf-system-not-found-behavior*=
+ =*clpm-dribble*=
+ =*context-diff-approval-method*=
#+TITLE: CLPM Configuration
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil H:9
......
#+TITLE: CLPM Sources
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
......@@ -75,7 +75,7 @@ The type of every source must be specified with a keyword.
The type specifier is =:clpi= and a =:url= is also required.
While CLPI sources *can* be synced, it is currently a fairly slow affair due
While CLPI sources can be synced, it is currently a fairly slow affair due
to how many objects the information is spread between. It is recommended
that you just let CLPM fetch data on demand.
......
#+TITLE: CLPM Storage
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
......
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