Commit 69e9471a authored by Eric Timmons's avatar Eric Timmons
Browse files

Documentation updates and clarifications

parent 4e41b3fe
Loading
Loading
Loading
Loading
+20 −25
Original line number Diff line number Diff line
@@ -94,14 +94,14 @@ files.
  Now that you have CLPM installed, this section walks you through how to set
  it up as a Quicklisp alternative.

  First, configure CLPM to use the Quicklisp index as a source for packages and
  to use HTTPS to fetch files from it [fn:1]. Create a file called
  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:

  #+begin_src common-lisp
    ("quicklisp"
     :type :quicklisp
     :url "https://beta.quicklisp.org/dist/quicklisp.txt")
     :type :ql-clpi
     :url "https://quicklisp.common-lisp-project-index.org/")
  #+end_src

  See [[file:docs/sources.org][sources]] for more details on configuring sources.
@@ -113,17 +113,8 @@ files.
    clpm client rc --quicklisp-alternative
  #+end_src

  Then, sync your local copy of the Quicklisp metadata by running:

  #+begin_src shell
    clpm sync
  #+end_src

  Syncing may take a while the first time as it needs to fetch and process the
  metadata for every Quicklisp release.

  Then you can start your favorite lisp and try loading a system, such as
  alexandria:
  Then you can start your favorite Common Lisp implementation and try loading a
  system, such as alexandria:

  #+begin_src common-lisp
    (asdf:load-system :alexandria)
@@ -167,12 +158,12 @@ files.
   everywhere possible. This trend is not going away, therefore CLPM should
   natively support HTTPS.

   As no Lisp implementation I am aware of has native support for TLS, this
   means that CLPM has to use third party tools to achieve this support. This
   further drives the separation of the core and client, as CLPM can use
   foreign libraries to provide TLS support and this is not something that
   should be brought into a development image that does not need it
   otherwise.
   As only LispWorks is the only Common Lisp implementation I am aware of that
   has native support for TLS, this means that CLPM has to use third party
   tools to achieve this support. This further drives the separation of the
   core and client, as CLPM can use foreign libraries to provide TLS support
   and this is not something that should be brought into a development image
   that does not otherwise need it.

   Additionally, Quicklisp packages are served over HTTPS. While the Quicklisp
   client cannot take advantage of that (without
@@ -189,7 +180,7 @@ files.
   To this end, CLPM can be used without ever loading the client (for example,
   =clpm bundle exec= configures ASDF entirely through environment variables)
   and if you do choose to use the client for better interactive development,
   CLPM is able to remove itself from the image when it is dumped.
   the client is able to remove itself from the image when it is dumped.

** Support CI/CD workflows

@@ -222,7 +213,7 @@ files.

   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
   of CLPI). This new Common Lisp Package Index includes both extra metadata
   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.
@@ -240,7 +231,11 @@ files.

* Footnotes

[fn:1] All files in the primary Quicklisp distribution are served over both
HTTPS and HTTP, even though the Quicklisp client cannot use HTTPS itself.
[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]].
+4 −4
Original line number Diff line number Diff line
@@ -43,10 +43,10 @@ with zero configuration or helpers needed (other than ASDF, of course).
*** ~:source~

    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
    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:

    #+begin_src common-lisp
+49 −10
Original line number Diff line number Diff line
@@ -44,8 +44,8 @@ The type of every source must be specified with a keyword.
     HTTPS scheme, then every interaction with this source will take place
     using HTTPS.

   For instance, to use the primary Quicklisp source, you use the following
   description:
   For instance, to use the primary Quicklisp distribution, you use the
   following description:

   #+begin_src common-lisp
     ("quicklisp"
@@ -53,16 +53,55 @@ The type of every source must be specified with a keyword.
      :url "https://beta.quicklisp.org/dist/quicklisp.txt")
   #+end_src

   Currently, information cannot be fetched from a Quicklisp distribution on
   demand, data must be synced between your computer and the distribution. This
   happens automatically when using =bundle= commands. In order to sync
   manually (for installing into a global context or when you expect to have
   bad internet soon), run the following, where =$SOURCE_NAME= is the name of
   the source in your config file:

   #+begin_src shell
     clpm sync $SOURCE_NAME
   #+end_src

** CLPI

   Common Lisp Package Index style sources are currently under development. At
   the moment, the only documentation of them exists in CLPM's source code. The
   goal is to produce a package index that contains all of the releases of
   projects, along with system versions and dependencies, and extra metadata
   such as upstream repo location.
   Common Lisp Project Index style sources are currently under development in
   the [[https://gitlab.common-lisp.net/clpm/clpi][CLPI project]].

   The primary CLPM author currently uses a CLPI style source to index packages
   located on a private Gitlab instance. If you are interested in using a CLPI
   style source, please reach out.
   located on a private Gitlab instance. If you are interested in doing
   something similar, please reach out.

   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
   to how many objects the information is spread between. It is recommended
   that you just let CLPM fetch data on demand.

** QL-CLPI

   This type of source is an extension of CLPI sources to include extra
   information relevant to representing a Quicklisp distribution in a CLPI
   style repository. Currently, this extra information includes version aliases
   as the same version of a project is routinely present in multiple Quicklisp
   distribution releases. Development of this source type happens in the
   [[https://gitlab.common-lisp.net/clpm/ql-clpi][QL-CLPI project]].

   The type designator for this source is =:ql-clpi=. It can be configured with
   the following options:

   + =:url= :: The URL to the index.

   For instance, to use the a mirror of the primary Quicklisp distribution, you
   use the following description:

   #+begin_src common-lisp
     ("quicklisp"
      :type :ql-clpi
      :url "https://quicklisp.common-lisp-project-index.org/")
   #+end_src

   The type specifier is =:clpi=.
   While QL-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.