CLPM Configuration

CLPM can be configured through environment variables or a file named clpm.conf. The clpm.conf file is found by constructing a list of directories to search and the first instance found wins. The default order of directories searched is first the clpm folder of the user's XDG config directory (typically ~/.confg/), then in the system config folder (typically /etc/). The order can be changed with the CLPM_CONFIG_DIRS environment variable. If specified, it must be a list of directories separated by your OS's conventional directory separator. If any entry in the list is empty. The default search locations will be spliced into the list.

The configuration is organized into many hierarchical tables with config values specified through environment variables overriding those specified in the file.

Logically, CLPM is configured by a series of nested tables. The config file describes these tables using a series of forms. Additionally, any value specified by environment variables overrides the values specified in the file. The first form in the config file declares the version of the config file API being used, such as the following. The described version API is 0.2.

(version "0.2")

Each subsequent form in the file must describe a table. Each subsequent form must start with a list containing the path to the table being described. The body of the form then contains a plist describing key/value pairs for that table.

For example, the following config would force CLPM to use dexador as its HTTP client and write ASDF source registry configuration for the "default" context to "/home/user/.config/common-lisp/source-registry.conf.d/50-clpm.conf"

(version "0.2")

((:contexts "default")
 :source-registry.d-files ("/home/user/.config/common-lisp/source-registry.conf.d/50-clpm.conf"))

((:http-client)
 :type :dexador)

The following describes the available configuration tables for CLPM. Each header describes a table. The lists in each section describe that table's keys.

The environment variable name for any config option can be determined by turning all hyphens into underscores and separating path elements with an underscore as well. For example, the HTTP client can be set to dexador by setting CLPM_HTTP_CLIENT_TYPE=dexador.

However, any path element that is a domain name must have periods replaced with two underscores, including after the TLD. For example, to set a password for authenticating to Github, you would set CLPM_GIT_REMOTES_GITHUB__COM__PASSWORD=supersekret

The current configuration can be printed by running clpm config info.

()

The root table, containing all other tables and some direct options.

:context
A string naming the default context.

:local
If true, sources do not download metadata from the internet. Currently, they may still download tarballs from the internet, but this may change in a future version.

(:archives)

This table contains all options for dealing with archives.

(:archives :tar)

This table contains configuration for dealing with archives in tar format.

:type
A keyword specifying which tar implementation use. Defaults to :auto.

(:bundle)

This table contains all configuration for operating with bundles.

:clpmfile
Pathname to the clpmfile used for bundle commands. Relative pathnames resolved relative to the current working directory.

:output-translation
Controls whether clpm bundle exec configures ASDF's output translations. NIL corresponds to not configuring the output translations. T (default) configures the output translations to translate everything to a folder in CLPM's cache. :local translates everything into the ./.clpm/fasl-cache/ folder relative to the clpmfile.

(:bundle :local)

This table contains configuration used to override project resolution when operating with bundles such that a local checkout of a project is used instead of an upstream version.

(:bundle :local "PROJECT-NAME")

When using the bundle commands, instead of using the upstream VCS for PROJECT-NAME, use a local checkout instead.

:path
Path to the folder containing the checkout of the git repository to use. Relative pathnames are resolved with respect to the directory of the clpmfile.

(:contexts)

This table contains configuration for all contexts.

(:contexts "CONTEXT-NAME")

This table contains the configuration for context CONTEXT-NAME.

:ignore-inherited-source-registry
Controls whether the source registry for this context ignores inherited configuration.

:output-translation
Controls whether ASDF output translations are used for a context. NIL corresponds to not configuring the output translations. T (default) configures the output translations to translate everything to a folder in CLPM's cache.

:source-registry.d-files
A list of pathnames. On any modification of a context, each file will be updated to contain the locations of all .asd files in the context, in a format suitable for inclusion in a source-registry.d directory (see ASDF manual).

:source-registry-files
A list of pathnames. On any modification of a context, each file will be updated to contain the locations of all .asd files in the context, in a format suitable for ASDF's source-registry.conf feature (see ASDF manual).

:sources
A list of global source names that this context can use, or T (default) to represent all global sources.

(:curl)

This table contains configuration for using the curl executable as an HTTP client.

:path
Path to the curl executable. Defaults to "curl".

(:firejail)

This table contains configuration for using the firejail executable as a sandbox method. (experimental)

:path
Path to the firejail executable. Defaults to "firejail".

(:git)

This table contains the configuration for interacting with git repositories.

(:git :remotes)

This table contains configuration specific to specified git remotes.

(:git :remotes "HOSTNAME")

This table contains configuration specific to interacting with the git remote located at HOSTNAME.

:username
A string containing the username to use when connecting to the server.

:password
A string containing the password to use when connecting to the server. Ignored when the method is not HTTPS.

:method
A keyword describing how to connect to the server. Can be one of:

:https
Connect using HTTPS.

:ssh
Connect using SSH.

(:grovel)

This table contains configuration for groveling for dependencies and other information from .asd files.

(:grovel :lisp)

This table contains the configuration on which Lisp implementation to use when groveling.

:command
The command to execute when starting the Lisp implementation. Needed only if using a non standard path. Is broken into a list of arugments using shlex.

:implementation
A keyword naming an implementation recognized by the lisp-invocation library or :custom. If :custom, the :command must start the implementation in the desired state.

:path
DEPRECATED - USE :command instead.

(:grovel :sandbox)

This table contains configuration of the sandbox used to isolate processes that grovel for dependencies from .asd files. (Experimental)

:method
The method to use to provide the sandbox. Defaults to :auto.

(:http)

This table contains the configuration for interacting with remote servers using HTTP (for non-VCS releated requests).

(:http :headers)

This table contains the configuration for specifying headers to be sent during HTTP requests.

(:http :headers "HOSTNAME")

This table contains the configuration for specifying headers to be sent during HTTP requests to host HOSTNAME.

(:http :headers "HOSTNAME" "HEADER-NAME")

This table contains the configuration for specifying the contents of HEADER-NAME to be sent during HTTP requests to host HOSTNAME.

:secure-only-p
If non-NIL, send this header only on secure connections.

:value
The value to send for the header. Must be a string.

:exec
A path to a file that, when executed, prints the header value to its standard output. Must be a string or pathname.

:contents
A path to a file that contains the value to use for the header. Must be a string or pathname.

(:http-client)

This table contains configuration for the internal HTTP client.

:type
A keyword specifying which HTTP client to use. Defaults to :auto.

(:log)

This table contains configuration for the logging system.

:level
A keyword specifying the default logging level. One of :off, :fatal, :error, :warn, :info, :debug, :trace. Defaults to :warn.

(:tar)

This table contains configuration for using the tar executable as the method to extract archives in tar format.

:path
Path to the tar executable. Defaults to "tar".