quicklisp - Library Manager

Version: 2020-01-04
Licence: BSD-style
Repository: quicklisp/quicklisp-client - Github

In case of any inaccuracies, ambiguities or suggestions, please create an issue here.

GETTING STARTED

Installation

Download

Do the equivalent steps on Windows and Mac OS:

curl -O https://beta.quicklisp.org/quicklisp.lisp     # download quicklisp.lisp
curl -O https://beta.quicklisp.org/quicklisp.lisp.asc # download the PGP signature file
gpg --verify quicklisp.lisp.asc quicklisp.lisp        # verify it against the signing key

As of 07 June 2020, Quicklisp release signing key has a fingerprint of D7A3 489D DEFE 32B7 D0E7 CC61 3079 65AB 028B 5FF7, an id of 028B5FF7, and an email of release@quicklisp.org. See here for the more recent details.

Installation

Load quicklisp.lisp: sbcl --load quicklisp.lisp # or an equivalent command for your implementation (optionally, you may want to rlwrap sbcl --load quicklisp.lisp for a better repl experience):

(quicklisp-quickstart:install)
(ql:add-to-init-file) ; to automatically load quicklisp at implementation startup
;;; Note that ql acts as a nickname for the quicklisp-client package.

quicklisp-quickstart:install also takes a couple keyword arguments (see (describe 'quicklisp-quickstart:install) - but unless you know what you are doing, it is recommended to leave them as they are.

Loading after installation

(ql:add-to-init-file) adds instructions to your implementations init-file (.sbclrc or equivalent) to load quicklisp on implementation startup.

However, some runtime options of the implementation may disable loading the init-file - sbcl --script for instance. For these cases, you might want to alias (or equivalent) alias sbcl-ql='rlwrap sbcl --noinform --load $HOME/quicklisp/setup.lisp' in your .bashrc (or equivalent).

A few useful functions and variables

  • quickload: (ql:quickload '("alexandria" "bordeaux-threads")) or (ql:quickload "alexandria").
  • system-apropos: (ql:system-apropos "postgres")
  • where-is-system
  • *local-project-directories*: you may either want to have this variable modified from implementation init-file, or symlink ~/quicklisp/local-projects to wherever your projects directory is. This is the location - as the name suggests - where quicklisp searches for local projects.
  • uninstall
  • update-client

You may also need to run (asdf:clear-configuration) to have ASDF reprocess its configuration files while loading a newer library. There is also the ql:register-local-projects that can help with the same.

A note on quicklisp dists

Besides being an ASDF system, quicklisp is also the name of a dist. This distribution is released about once per month, with the guarantee that all systems in the distribution build together - note that this does not still imply that they work together. For these cases, you may want to go back in dist time. You might, additionally, want to learn about qlot that helps with version pinning - however, given the stability of Common Lisp, that translates to the stability for its (old but gold) libraries, it may be an overkill. But, YMMV.

Also worth a read is getting libraries into quicklisp. (Hope you took note of the blog!)

The once-per-month release nature of quicklisp can be an issue if you need to work with bleeding edge packages - for these cases, there exists Ultralisp - which updates every 5 minutes! This is yet another distribution. Some useful functions for working with distributions include:

More reading

More reading about quicklisp is available on its official page.

quicklisp-client: API REFERENCE

Nickname: ql

The Quicklisp client package, intended for end-user Quicklisp commands and configuration parameters.

*local-project-directories*

Variable

The default local projects directory.

*quickload-prompt*

Variable

When NIL, quickload systems without prompting for enter to continue, otherwise proceed directly without user intervention.

*quickload-verbose*

Variable

When NIL, show terse output when quickloading a system. Otherwise, show normal compile and load output.

add-to-init-file

Function: (add-to-init-file &optional implementation-or-file)

Add forms to the Lisp implementation's init file that will load quicklisp at CL startup.

available-client-versions

Function: (available-client-versions)

available-dist-versions

Function: (available-dist-versions name)

bundle-systems

Function: (bundle-systems system-names &key include-local-projects to
                          (overwrite t))

In the directory to, construct a self-contained bundle of libraries based on system-names. For each system named, and its recursive required systems, unpack its release archive in TO/software/, and write a system index, compatible with the output of QL:write-asdf-manifest-file, to TO/system-index.txt. Write a loader script to TO/bundle.lisp that, when loaded via CL:LOAD, configures ASDF to load systems from the bundle before any other system.

system-names must name systems provided directly by Quicklisp.

If include-local-projects is true, each directory in QL:LOCAL-PROJECT-DIRECTORIES is copied into the bundle and loaded before any of the other bundled systems.

client-url

Function: (client-url)

Return an URL suitable for passing as the :URL argument to install-client for the current local client installation.

client-version

Function: (client-version)

Return the version for the current local client installation. May or may not be suitable for passing as the :VERSION argument to install-client, depending on if it's a standard Quicklisp-provided client.

config-value

Function: (config-value path)

dist-url

Function: (dist-url name)

dist-version

Function: (dist-version name)

help

Function: (help)

install-client

Function: (install-client &key url version)

list-local-projects

Function: (list-local-projects)

Return a list of pathnames to local project system files.

list-local-systems

Function: (list-local-systems)

Return a list of local project system names.

local-projects-searcher

Function: (local-projects-searcher system-name)

This function is added to ASDF:SYSTEM-DEFINITION-SEARCH-FUNCTIONS to use the local project directory and cache to find systems.

provided-systems

Generic Function: (provided-systems object)

Return a list of systems provided by object.

qmerge

Function: (qmerge pathname)

Return pathname merged with the base Quicklisp directory.

quickload

Generic Function: (quickload systems &key verbose silent prompt explain
                   &allow-other-keys)

Load systems the quicklisp way. systems is a designator for a list of things to be loaded.

register-local-projects

Function: (register-local-projects)

Force a scan of the local projects directory to create the system file index.

setup

Function: (setup)

system-apropos

Generic Function: (system-apropos term)

system-apropos-list

Generic Function: (system-apropos-list term)

system-list

Function: (system-list)

system-not-found

Condition

This condition is signaled by QUICKLOAD when a system given to load is not available via ASDF or a Quicklisp dist.

Direct Slots

ql-dist:name

Initargs: :NAME
Readers: SYSTEM-NOT-FOUND-NAME

system-not-found-name

Generic Function: (system-not-found-name condition)

uninstall

Function: (uninstall system-name)

uninstall-dist

Function: (uninstall-dist name)

update-all-dists

Function: (update-all-dists &key (prompt t))

update-client

Function: (update-client &key (prompt t))

update-dist

Function: (update-dist dist &key (prompt t))

use-only-quicklisp-systems

Function: (use-only-quicklisp-systems)

where-is-system

Function: (where-is-system name)

Return the pathname to the source directory of ASDF system with the given name, or NIL if no system by that name can be found known.

who-depends-on

Function: (who-depends-on system-name)

Return a list of names of systems that depend on system-name.

write-asdf-manifest-file

Function: (write-asdf-manifest-file output-file &key
           (if-exists :rename-and-delete) exclude-local-projects)

Write a list of system file pathnames to output-file, one per line, in order of descending QL-DIST:PREFERENCE.

ql-dist: API Reference

Generic functions, variables, and classes for interacting with the dist system. Documented, exported symbols are intended for public use.

*dist-enumeration-functions*

Variable

all-dists calls each function in this list with no arguments, and appends the results into a list of dist objects, removing duplicates. Functions might be called just once for a batch of related operations; see with-consistent-dists.

all-dists

Function: (all-dists)

Return a list of all known dists.

archive-content-sha1

Generic Function: (archive-content-sha1 object)

archive-md5

Generic Function: (archive-md5 object)

archive-size

Generic Function: (archive-size object)

archive-url

Generic Function: (archive-url release)

Return the full URL for fetching the archive file of release.

available-update

Generic Function: (available-update dist)

If an update is available for dist, return the update as an uninstalled dist object. Otherwise, return NIL.

available-versions

Generic Function: (available-versions object)

Return a list of version information for object.

available-versions-url

Generic Function: (available-versions-url object)

Return the URL for the available versions data file of object.

badly-sized-local-archive

Condition

base-directory

Generic Function: (base-directory object)

Return the base directory pathname of object.

canonical-distinfo-url

Generic Function: (canonical-distinfo-url object)

check-local-archive-file

Generic Function: (check-local-archive-file release)

Check the local archive file of release for validity, including size and signature checks. Signals errors in the case of invalid files.

clean

Generic Function: (clean object)

Remove any unneeded files or directories related to object.

dependency-tree

Generic Function: (dependency-tree system)

disable

Generic Function: (disable object)

Disable object.

dist

Generic Function: (dist object)

Return the dist of object.

Class

Direct Slots

base-directory

Initargs: :BASE-DIRECTORY
Readers: BASE-DIRECTORY
Writers: (SETF BASE-DIRECTORY)

name

Initargs: :NAME
Readers: NAME
Writers: (SETF NAME)

version

Initargs: :VERSION
Readers: VERSION
Writers: (SETF VERSION)

system-index-url

Initargs: :SYSTEM-INDEX-URL
Readers: SYSTEM-INDEX-URL
Writers: (SETF SYSTEM-INDEX-URL)

release-index-url

Initargs: :RELEASE-INDEX-URL
Readers: RELEASE-INDEX-URL
Writers: (SETF RELEASE-INDEX-URL)

available-versions-url

Initargs: :AVAILABLE-VERSIONS-URL
Readers: AVAILABLE-VERSIONS-URL
Writers: (SETF AVAILABLE-VERSIONS-URL)

canonical-distinfo-url

Initargs: :CANONICAL-DISTINFO-URL
Readers: CANONICAL-DISTINFO-URL
Writers: (SETF CANONICAL-DISTINFO-URL)

provided-systems

Initargs: :PROVIDED-SYSTEMS
Readers: PROVIDED-SYSTEMS
Writers: (SETF PROVIDED-SYSTEMS)

provided-releases

Initargs: :PROVIDED-RELEASES
Readers: PROVIDED-RELEASES
Writers: (SETF PROVIDED-RELEASES)

enable

Generic Function: (enable object)

Enable object.

enabled-dists

Function: (enabled-dists)

Return a list of all known dists for which enabledp returns true.

enabledp

Generic Function: (enabledp object)

Return true if object is enabled.

ensure-installed

Generic Function: (ensure-installed object)

Ensure that object is installed.

ensure-local-archive-file

Generic Function: (ensure-local-archive-file release)

If the archive file for release is not available locally, fetch it and return the pathname to it.

find-asdf-system-file

Function: (find-asdf-system-file name)

Return the ASDF system file in which the system named name is defined.

find-dist

Function: (find-dist name)

find-dist-or-lose

Function: (find-dist-or-lose name)

find-release

Generic Function: (find-release name)

Return a release with the given name, or NIL if no system is found. If multiple releases have the same name, the one with the highest preference is returned.

find-release-in-dist

Generic Function: (find-release-in-dist release-name dist)

Return a release with the given name in dist, or NIL if no release is found.

find-system

Generic Function: (find-system name)

Return a system with the given name, or NIL if no system is found. If multiple systems have the same name, the one with the highest preference is returned.

find-system-in-dist

Generic Function: (find-system-in-dist system-name dist)

Return a system with the given name in dist, or NIL if no system is found.

forget-preference

Generic Function: (forget-preference object)

Remove specific preference information for object.

inhibit-subscription

Generic Function: (inhibit-subscription object)

Inhibit subscription for object.

initialize-release-index

Generic Function: (initialize-release-index dist)

Initialize the release index of dist.

initialize-system-index

Generic Function: (initialize-system-index dist)

Initialize the system index of dist.

install

Generic Function: (install object)

Install object.

install-dist

Function: (install-dist url &key (prompt t) replace)

install-metadata-file

Generic Function: (install-metadata-file object)

The pathname to a file describing the installation status of object.

installed-releases

Generic Function: (installed-releases dist)

Return a list of all releases installed for dist.

installed-systems

Generic Function: (installed-systems dist)

Return a list of all systems installed for dist.

installedp

Generic Function: (installedp object)

Return true if object is installed.

invalid-local-archive

Condition

Direct Slots

release

Initargs: :RELEASE
Readers: INVALID-LOCAL-ARCHIVE-RELEASE

invalid-local-archive-file

Generic Function: (invalid-local-archive-file condition)

invalid-local-archive-release

Generic Function: (invalid-local-archive-release condition)

local-archive-file

Generic Function: (local-archive-file release)

Return the pathname to where the archive file of release should be stored.

metadata-name

Generic Function: (metadata-name object)

The metadata-name of an object is used to form the pathname for a few different object metadata files.

missing-local-archive

Condition

name

Generic Function: (name object)

Return the name of object.

new-version-available-p

Generic Function: (new-version-available-p dist)

Return true if a new version of dist is available.

preference

Generic Function: (preference object)

Returns a value used when comparing multiple systems or releases with the same name. Objects with higher preference are returned by find-system and find-release.

preference-file

Generic Function: (preference-file object)

Return the file from which preference information is loaded for object.

preference-parent

Generic Function: (preference-parent object)

Return a value suitable for checking if object has no specific preference set.

prefix

Generic Function: (prefix object)

project-name

Generic Function: (project-name object)

provided-releases

Generic Function: (provided-releases object)

Return a list of releases provided by object.

provided-systems

Generic Function: (provided-systems object)

Return a list of systems provided by object.

relative-to

Generic Function: (relative-to object pathname)

Merge pathname with the base-directory of object.

release

Generic Function: (release object)

Return the release of object.

Class

Instances of this class represent a snapshot of a project at some point in time, which might be from version control, or from an official release, or from some other source.

Direct Slots

project-name

Initargs: :PROJECT-NAME

dist

Initargs: :DIST

provided-systems

Initargs: :PROVIDED-SYSTEMS
Readers: PROVIDED-SYSTEMS
Writers: (SETF PROVIDED-SYSTEMS)

archive-url

Initargs: :ARCHIVE-URL
Readers: ARCHIVE-URL
Writers: (SETF ARCHIVE-URL)

archive-size

Initargs: :ARCHIVE-SIZE
Readers: ARCHIVE-SIZE
Writers: (SETF ARCHIVE-SIZE)

archive-md5

Initargs: :ARCHIVE-MD5
Readers: ARCHIVE-MD5
Writers: (SETF ARCHIVE-MD5)

archive-content-sha1

Initargs: :ARCHIVE-CONTENT-SHA1
Readers: ARCHIVE-CONTENT-SHA1
Writers: (SETF ARCHIVE-CONTENT-SHA1)

prefix

Initargs: :PREFIX

system-files

Initargs: :SYSTEM-FILES
Readers: SYSTEM-FILES
Writers: (SETF SYSTEM-FILES)

metadata-name

Initargs: :METADATA-NAME
Readers: METADATA-NAME
Writers: (SETF METADATA-NAME)

release-index-url

Generic Function: (release-index-url object)

Return the URL for the release index of object.

required-systems

Generic Function: (required-systems object)

short-description

Generic Function: (short-description object)

Return a short string describing object.

show-update-report

Generic Function: (show-update-report old-dist new-dist)

Display a description of the update from old-dist to new-dist.

standard-dist-enumeration-function

Function: (standard-dist-enumeration-function)

The default function used for producing a list of dist objects.

subscribe

Generic Function: (subscribe object)

Subscribe to updates of object, if possible. If no updates are available, a condition of type subscription-unavailable is raised.

subscribedp

Generic Function: (subscribedp object)

Return true if object is subscribed to updates.

subscription-inhibited-p

Generic Function: (subscription-inhibited-p object)

Return T if subscription to object is inhibited.

subscription-inhibition-file

Generic Function: (subscription-inhibition-file object)

The file whose presence indicates the inhibited subscription status of object.

subscription-unavailable

Condition

subscription-url

Generic Function: (subscription-url object)

system

Generic Function: (system object)

Return the system of object.

Class

Direct Slots

name

Initargs: :NAME

system-file-name

Initargs: :SYSTEM-FILE-NAME
Readers: SYSTEM-FILE-NAME
Writers: (SETF SYSTEM-FILE-NAME)

release

Initargs: :RELEASE

dist

Initargs: :DIST
Readers: DIST
Writers: (SETF DIST)

required-systems

Initargs: :REQUIRED-SYSTEMS
Readers: REQUIRED-SYSTEMS
Writers: (SETF REQUIRED-SYSTEMS)

metadata-name

Initargs: :METADATA-NAME
Readers: METADATA-NAME
Writers: (SETF METADATA-NAME)

system-apropos

Generic Function: (system-apropos term)

system-apropos-list

Generic Function: (system-apropos-list term)

system-definition-searcher

Function: (system-definition-searcher name)

Like find-asdf-system-file, but this function can be used in ASDF:SYSTEM-DEFINITION-SEARCH-FUNCTIONS; it will only return system file names if they match name.

system-file-name

Generic Function: (system-file-name object)

system-files

Generic Function: (system-files object)

system-index-url

Generic Function: (system-index-url object)

Return the URL for the system index of object.

uninhibit-subscription

Generic Function: (uninhibit-subscription object)

Remove inhibition of subscription for object.

uninstall

Generic Function: (uninstall object)

Uninstall object.

unknown-dist

Condition

Direct Slots

name

Initargs: :NAME
Readers: :UNKNOWN-DIST-NAME

unsubscribe

Generic Function: (unsubscribe object)

Unsubscribe from updates to object.

update-in-place

Generic Function: (update-in-place old-dist new-dist)

Update old-dist to new-dist in place.

update-release-differences

Generic Function: (update-release-differences old-dist new-dist)

Compare old-dist to new-dist and return three lists as multiple values: new releases (present in new-dist but not old-dist), changed releases (present in both dists but different in some way), and removed releases (present in old-dist but not new-dist). The list of changed releases is a list of two-element lists, with each two-element list having first the old release object and then the new release object.

version

Generic Function: (version object)

with-consistent-dists

Macro: (with-consistent-dists &body body)

See CALL-WITH-CONSISTENT-DISTS.