Commit a7d90f14 authored by Cameron Pittman's avatar Cameron Pittman
Browse files

Clean up wording; remove misleading statements

parent 1ec7a1dc
Pipeline #5300 failed with stages
in 33 minutes and 37 seconds
......@@ -249,16 +249,15 @@ appropriate tag or see [[http://www.clpm.dev]].
development versions) as well as information on the ASDF system version
numbers.
* Introduction to Dependency Management for Lisp Novices
* Introduction to Dependency Management for Common Lisp Novices
A project in lisp may have external dependencies, which are generally called
/systems/ in the lisp community. Importing a system can be as easy as loading
another lisp file from your filesystem. Or it can be much more complex,
A project in Common Lisp (CL) is made of systems. The project and its systems
may have external dependencies. Using a dependency can be as easy as loading
another ~.lisp~ file from your filesystem. Or it can be much more complex,
especially when you're facing the realities of distributing useful software with
complex functionality across platforms and architectures. What's needed in that
case is a build tool. For most lisps, including SBCL, that tool is [[https://common-lisp.net/project/asdf/][ASDF]]. ASDF
manages the tasks of loading and building systems in SBCL. The ASDF
documentation sums it up as:
case is a build tool. For CL, that tool is [[https://common-lisp.net/project/asdf/][ASDF]]. ASDF manages the tasks of
loading and building systems in SBCL. The ASDF documentation sums it up as:
#+begin_quote
...it orchestrates the compilation and dependency management, handles some of
......@@ -274,10 +273,9 @@ ASDF is also very clear in its documentation that it "will not download missing
software components for you." For that, users must turn to other tools. Manually
installing dependencies at a path ASDF recognizes is always an option.
Otherwise, [[http://quicklisp.org/][Quicklisp]] is a popular system installer with an associated online
registry of metadata it uses to search and retrieve systems. It's the /de facto/ /
historical choice for the lisp community. That being said, it falls short on
modern features - no support for HTTPS, no support for git repos, and no
versioning. That's where [[https://clpm.dev][CLPM]] comes in.
registry of metadata it uses to search and retrieve systems. For CL, it's the /de facto/
choice. That being said, it falls short on modern features - no support for
HTTPS, no support for git repos, and no versioning. That's where [[https://clpm.dev][CLPM]] comes in.
CLPM's core functionality is the same as Quicklisp - (1) it tells ASDF where to
find external systems, and (2) it takes care of installing (downloading)
......@@ -290,8 +288,8 @@ external systems. Let's break down what happens in each phase at a high-level.
~$XDG_DATA_HOME/clpm~. It may use Quicklisp's existing metadata registry or a
newer standard called [[https://gitlab.common-lisp.net/clpm/clpi][CLPI]] to find systems
Thus, when a user asks ASDF to interact with an external system, ASDF knows to
look in ~$CLPM_DATA_DIR~ to find the ~.asd~ and ~.lisp~ files it needs.
Thus, when a user asks ASDF to find an external system, ASDF knows to look in
~$CLPM_DATA_DIR~ to find the ~.asd~ and ~.lisp~ files it needs.
The last piece of core functionality of CLPM worth understanding is its ability
for users to organize dependencies using contexts. When you want to use CLPM,
......@@ -301,12 +299,10 @@ exploring systems, while per-project contexts provide a technique for locking
dependency versions for reproducible builds. Each project may also declare its
dependencies to CLPM in an aptly named ~clpmfile~.
/NOTE: this project/ automatically /activates the/ ~default~ /context./
While the concept of per-project contexts may sound similar to, say, using
~bundler~ with Ruby, ~npm~'s ~node_modules~ directory for JavaScript, or
activating a virtualenv in Python, you should be aware of how the implementation
details of a context and their interaction with lisp impacts their behavior. For
details of a context and their interaction with CL impacts their behavior. For
starters, all systems, whether global or per-project, are installed to the same
~$CLPM_DATA_DIR~. CLPM will happily keep different versions of the same project
installed for you, though. CLPM is also recursive in that it installs
......@@ -316,34 +312,31 @@ parsing each dependency's ~clpmfile~. Like a ~package-lock.json~ file in a
Node.js project, CLPM writes a ~clpmfile.lock~ automatically with the full tree
of all recursive dependencies. Finally, and most importantly, it is not safe to
switch contexts on the fly. The issue with switching contexts gets to the heart
of how lisp is different than many other languages.
of how CL is different than many other languages.
Remember that a lisp image (the functions and variables loaded in a REPL) is
Remember that a CL image (the functions and variables loaded in a REPL) is
both longer-living and more dynamic than the runtimes for other languages. You
switch contexts /from within the runtime itself/, not through an external
process (like a shell) that invokes the runtime. Thus, if you load a system with
ASDF and then switch contexts, /that first system is still loaded/. If you try
to then load another version of the same system in your new context, you're
still in the same runtime and you may find that the old system is still there.
In the interaction between CLPM, ASDF, SLIME, and lisp, both ASDF and CLPM have
In the interaction between CLPM, ASDF, SLIME, and CL, both ASDF and CLPM have
the concept of a version (more on this below). However, ASDF does not have the
concept of installing multiple versions simultaneously and switching between
them given project requirements. To ASDF, asking it to load a different version
of a system is the same as asking it to load the same system twice. The new
version might replace the old one, it might not. It depends on how the system is
defined and whether or not it cleans up after itself when it loads (which is
unlikely).
version might clean up the old one, but it likely won't. It depends on whether
the author(s) of the system programmed clean up behavior.
So here is what you should be thinking when you fire up SLIME:
1. I need to activate a CLPM context so CLPM knows where I'm working
(~default~ is activated automatically by this project - you should
immediately switch to another context if you don't want it)
2. If I haven't installed my dependencies yet, let me tell CLPM to start
installing the external systems I need
3. Now that I have my dependencies on my machine, I can start asking ASDF to
load them so I can use them
4. Time to ~C-c C-c~ on some lisp!
4. Time to ~C-c C-c~ on some CL!
*** Dos and Don'ts of Versioning with CLPM and ASDF
......@@ -355,9 +348,9 @@ Think of a ~clpmfile~ as a /constraint/ on the environment moreso than a
CLPM where it can find dependencies, eg. private git repositories, Quicklisp
metadata, and CLPI.
You should *not* provide versions in a ~clpmfile~ unless you can articulate why
doing so could make your life more difficult. That being said, here are a few
reasons why you might want to constrain the versions of your dependencies with CLPM.
As a rule of thumb, you should avoid including versions in a ~clpmfile~.
However, here are a few reasons why you might want to constrain the versions of
your dependencies with CLPM.
1. DO version with CLPM if you want to use an unreleased version of a system.
Say you want to use the latest commits from another repository that haven't
......@@ -365,8 +358,7 @@ reasons why you might want to constrain the versions of your dependencies with C
and commit. Note however this should be considered a temporary measure and
reverted to a normal release (ie. pointing to Quicklisp metadata) once the
functionality you need in the system is available normally.
2. DO put bounds on versions with CLPM. ASDF does not support bounding versions
using semver, but CLPM does. If you want to avoid certain versions of
2. DO put bounds on versions with CLPM. If you want to bound the versions of
systems for whatever reason, use CLPM.
3. DO add development-only dependencies with CLPM. This is similar to the
concept of ~devDependencies~ in a JavaScript ~package.json~ file. If there
......@@ -375,8 +367,9 @@ reasons why you might want to constrain the versions of your dependencies with C
Here are a few reasons to avoid versioning with CLPM.
1. DO NOT version with CLPM if you have already specified a version in ASDF and
you are happy with the version of the system that CLPM installs.
1. DO NOT add constraints to a ~clpmfile~ if you have already specified a
version in ASDF and you are happy with the version of the system that CLPM
installs.
2. DO NOT version with CLPM just because you can provide a version. Assume ASDF
is the source of truth for the versions of dependencies.
......
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