Commit 7a3a35cd authored by Eric Timmons's avatar Eric Timmons
Browse files

Documentation improvement

parent f065e9e5
......@@ -3,7 +3,7 @@
#+EMAIL: etimmons@mit.edu
#+OPTIONS: email:t toc:2 num:nil
**WARNING**: This is BETA quality. It is being published right now so I can
**WARNING**: This is ALPHA quality. It is being published right now so I can
start testing it and hammering at it in my normal work flow. There are probably
bugs and it may eat your files.
......@@ -20,6 +20,10 @@ bugs and it may eat your files.
the CLI program as necessary to find and install missing systems. This piece
is generally referred to as the CLPM client.
Currently, the project specific context management is the most mature. Version
0.1.0 will be released when both the global and project specific features are
usable.
* Project Goals
CLPM is far from the only package manager available for Common Lisp[fn:1], but
......@@ -53,7 +57,8 @@ bugs and it may eat your files.
+ Support multiple package sources :: At first, CLPM will support only
Quicklisp-style distributions as a package source/repository. But we
envision adding support for new sources, such as Qi and a new work in
progress repo geared toward projects that follow versioning guidelines.
progress repository geared toward projects that follow versioning
guidelines.
* Documentation
......
......@@ -48,6 +48,7 @@ configuration or helpers needed (other than ASDF, of course).
#+begin_src common-lisp
(:source "quicklisp"
:type :quicklisp
:url "https://beta.quicklisp.org/dist/quicklisp.txt"
:force-https t)
#+end_src
......@@ -74,7 +75,7 @@ configuration or helpers needed (other than ASDF, of course).
+ ~:commit~ :: If specified, must be a string naming the commit to use.
+ ~:tag~ :: If specified, must be a string naming the tag to use.
+ ~:systems~ :: A list naming the systems to require in the bundle. If NIL,
all explicitly defined systems are required.
all explicitly defined systems are required.[fn:3]
*** ~:asd~
This directive states that the specified asd file should be included in the
......@@ -99,6 +100,14 @@ configuration or helpers needed (other than ASDF, of course).
source control is assumed to satisfy any requirements placed on it. No formal
commitment to syntax for this file is guaranteed yet.
* Configuration
Every bundle command reads the file =.clpm/bundle.conf= (if it exists) and
merges the configuration defined in that file into CLPM's config. Currently,
all configuration sections are merged, in a future version a whitelist of
configuration options will be defined.
* Commands
** =clpm bundle install=
......@@ -112,12 +121,24 @@ configuration or helpers needed (other than ASDF, of course).
will have access to all systems included in the bundle with no extra
configuration. Requires the lock file to exist.
All environment variables are passed on to the new process, additionally the
following environment variables are set:
+ =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.
+ =CLPM_BUNDLE_CLPMFILE= :: Set to the path to the clpmfile that defines the
bundle.
+ =CLPM_BUNDLE_CLPMFILE_LOCK= :: Set to the path to the clpmfile.lock that
defines the bundle.
* Comparisons
In the Common Lisp world, CLPM's bundle is most similar to [[https://github.com/fukamachi/qlot][Qlot]]. Unlike Qlot,
however, CLPM has the following features:
+ Has no dependency on roswell.
+ Does not use the Quicklisp client under the hood.
+ Has no dependency on roswell for its command line executable.
+ Is distributed both as source and an executable.
+ Works harder to determine dependencies of systems fetched from git.
+ Allows for more complex version specifications in the clpmfile.
......
#+TITLE: CLPM Configuration
CLPM is configured using toml configuration files.
* Configuration Values
** git
*** remotes
This table contains options for connecting to remote git servers. Each key
in the table must be the hostname of the remote server (in all
lowercase). The value of each key is a table containing the following
values:
| key | Type | value |
|----------+--------+----------------------------------------------------------------------------------|
| type | String | The type of the remote server |
| method | String | The preferred method for fetching code. Can be one of "https" (default) or "ssh" |
| username | String | The username to use when fetching over https. |
| password | String | The password to use when fetching over https. |
** http
*** headers
This table provides a mechanism to specify headers to send to servers when
downloading files over HTTP(S). This does *not* work when fetching git repos
over HTTP(S), see [[*remotes]] instead.
Each key in this table is the hostname of a server (in all lowercase) and
the values are tables, where each table maps a header name to either a
string or another table. If the header name is mapped to a string, that
string is sent as the value of the header. If the header name is mapped to
another table, the following keys are recognized. Behavior is undefined if
both =value= and =exec= are provided.
| key | type | value |
|-------------+---------+------------------------------------------------------------------------------|
| secure-only | Boolean | If true, this header is sent only over HTTPS connections. Defaults to false. |
| value | String | This value is used as the value of the header. |
| exec | String | Must point to an executable that prints out the value to use to its stdout. |
For example, you can use the following to access release tarballs from
private projects on gitlab.com using a Personal Access Token.
#+begin_src conf-toml
[http.headers."gitlab.com"]
private-token = { exec = "command-that-prints-my-pat" , secure-only = true}
#+end_src
** grovel
*** sandbox
This table lets you configure the sandboxing mechanism used when locally
determining (groveling for) the dependencies of some ASDF system. Currently
accepts the following keys:
| key | type | value |
|--------+--------+-----------------------------------------------|
| method | string | The sandbox method to use. Defaults to "auto" |
CLPM is configured using a file named =clpm.conf=. CLPM constructs a list of
directories to search for this file and the first instance found wins. The
default order of directories searched is first the =common-lisp/clpm= folder of
the user's XDG config directory (typically =$HOME/.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. The default
search locations will be spliced into the list if any entry in the list is
empty.
The contents of this file must be a single list that starts with ~clpm-config~
and the rest must be a plist. Each key in the plist names either a value or a
section. If it names a section, the value must be another plist. If it names a
value, the value is read according to the rules for that value.
The following describe the configuration options for clpm.
* ~:archives~
+ ~:tar-method~ :: A keyword specifying which tar implementation to
use. Defaults to =:auto=.
** ~:tar~
Settings for the tar method that uses an external tar program.
+ ~:path~ :: Path to the =tar= executable. Defaults to ="tar"=.
* ~:bundle~
** ~:local~
*** ~"PROJECT-NAME"~
When using the bundle commands, instead of using the upstream git repository
for PROJECT-NAME, use a local checkout instead.
+ ~:path~ :: Path to the folder containing the checkout of the git
repository to use.
* ~:git~
** ~:remotes~
*** ~"HOSTNAME"~
Provide configuration for interacting with HOSTNAME to fetch git repos.
+ ~: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.
+ ~:method~ :: A keyword describing how to connect to the server. Can be one
of:
+ ~:https~ :: Connect using HTTPS.
+ ~:http~ :: Connect using HTTP.
+ ~:ssh~ :: Connect using SSH.
+ ~:port~ :: Port to connect on.
* ~:http~
** ~:headers~
*** ~"HOSTNAME~
**** ~"HEADER-NAME"~
When performing a non-git HTTP request to HOSTNAME, provide a header with
the name HEADER-NAME.
+ ~:secure-only-p~ :: If non-NIL, send this header only on secure
connections.
+ ~:value~ :: The value to send for the header. If a string, the contents
of the string are used literally. If a pathname naming an
executable file, that file is executed and whatever it prints
to its standard output is used as the value. If a pathname
naming a non-executable file, the contents of the file are
sent.
* ~:http-client~
+ ~:method~ :: The default method to use to as an HTTP client. Defaults to
=:auto=.
** ~:curl~
Settings for the curl method that uses an external curl program.
+ ~:path~ :: Path to the =curl= executable. Defaults to ="curl"=.
* ~:grovel~
** ~:sandbox~
Options for configuring the sandbox used to isolate processes that grovel for
dependencies from .asd files.
+ ~:method~ :: The default method to use as the sandbox. Defaults to =:auto=.
* ~:sources~
** ~"SOURCE-NAME~
Options to configure the source with the name SOURCE-NAME. See [[file:sources.org][sources.org]]
for more information on the available sources and their configuration
options.
Must contain a value for ~:type~ that names the type of source this is.
......@@ -2,12 +2,6 @@
#+AUTHOR: Eric Timmons
#+EMAIL: etimmons@mit.edu
* Terminology
This section defines the various terms used throughout CLPM.
+ Source :: A repository of Common Lisp projects.
+ Distribution :: A software repository. Called a source in CLPM
terminology.
+ Distribution Version ::
+ [[file:config.org][config.org]]
+ [[file:sources.org][sources.org]]
+ [[file:bundle.org][bundle.org]]
......@@ -3,7 +3,7 @@
A repository of Common Lisp projects is called a "source". The source you are
most likely familiar with is Quicklisp, but CLPM is designed to use multiple
sources and source types. This allows you to easily use CLPM for things such as
internal projects that can't be release to private repositories.
internal projects that can't be released to public repositories.
Currently, the only type of source that CLPM publicly supports is a Quicklisp
style source. The author is currently working on and testing a new source type
......@@ -11,9 +11,7 @@ that improves upon Quicklisp, though (such as tracking of individual system
versions). If you are interested in trying out that source type, feel free to
reach out.
The type of every source can be specified. If not specified, CLPM will attempt
to guess the source type based on the file located at the specified URL. It is
recommended that the type be specified, however.
The type of every source must can be specified with a keyword.
* Quicklisp
......@@ -24,7 +22,7 @@ recommended that the type be specified, however.
https://beta.quicklisp.org/dist/quicklisp-versions.txt) that points to the
dist file for every version of the distribution.
The type designator for a Quicklisp like source is "quicklisp". A quicklisp
The type designator for a Quicklisp like source is =:quicklisp=. A quicklisp
distribution can be configured with the following options:
+ =url= :: The URL to the subscription metadata file.
......@@ -37,9 +35,11 @@ recommended that the type be specified, however.
The following table can be added to your CLPM config file to use the primary
Quicklisp distribution.
#+begin_src conf-toml
[sources.quicklisp]
type = "quicklisp"
url = "http://beta.quicklisp.org/dist/quicklisp.txt"
force-https = true
#+begin_src common-lisp
(clpm-config
:sources
("quicklisp"
(:type :quicklisp
:url "https://beta.quicklisp.org/dist/quicklisp.txt"
:force-https t)))
#+end_src
Markdown is supported
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