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
Loading
Loading
Loading
Loading
+38 −29
Original line number Diff line number Diff line
#+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]].
+1 −0
Original line number Diff line number Diff line
@@ -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))))")
+1 −7
Original line number Diff line number Diff line
#+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=

+25 −30
Original line number Diff line number Diff line
#+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*=
+1 −1
Original line number Diff line number Diff line
#+TITLE: CLPM Configuration
#+AUTHOR: CLPM Developers
#+AUTHOR: Eric Timmons
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil H:9

Loading