Commit c825a86c authored by Eric Timmons's avatar Eric Timmons
Browse files

Preparing for website

parent 45193458
#+TITLE: Installing CLPM
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: email:t toc:2 num:nil
#+OPTIONS: email:t toc:1 num:nil
CLPM is distributed in both source and binary form. For either version, first
install the dependencies:
......@@ -12,9 +12,6 @@ install the dependencies:
dependencies (likely needed if you use development versions of any
dependency). SBCL is required if you are installing from source.
After installing CLPM core, it is recommended you also install the CLPM client
(see [[file:doc/client.org][client.org]]), but it is not needed for the quickstart.
* Prebuilt binaries
To install CLPM in binary form, download the appropriate file from
[[https://common-lisp.net/project/clpm/downloads/][https://common-lisp.net/project/clpm/downloads/]]. Each release of CLPM
......
Copyright 2018-2019 Eric Timmons
Copyright 2018-2020 Eric Timmons
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
......
#+TITLE: Common Lisp Package Manager - CLPM
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: email:t toc:2 num:nil
#+OPTIONS: email:t toc:1 num:ni
**WARNING**: This software is BETA quality. I use it as my daily driver, but it
*WARNING*: This software is BETA quality. I use it as my daily driver, but it
is still a little rough around the edges and it may accidentally eat your
files.
......@@ -23,12 +24,68 @@ files.
referred to as the CLPM client or =clpm-client= and is meant to be loaded
when you are interactively developing code.
To contact the developers, send email to clpm-devel@common-lisp.net
[[https://mailman.common-lisp.net/listinfo/clpm-devel]].
CLPM is licensed under the two clause BSD license (BSD-2). So, basically do
what you want with it (while providing appropriate attribution) and don't
complain if it breaks things. CLPM is currently beta quality so expect some
breakage and incompatibilites going forward.
To receive help or report issues please send email to
[[mailto:clpm-devel@common-lisp.net][clpm-devel@common-lisp.net]]. Additionally, feel free to join the email list at
[[https://mailman.common-lisp.net/listinfo/clpm-devel]]. To join in the
development of CLPM, you can find the project hosted on the common-lisp.net
Gitlab server at [[https://gitlab.common-lisp.net/clpm/clpm]].
* Installing
See [[file:INSTALL.org][INSTALL.org]] for detailed installation instructions.
CLPM is distributed in both source and binary form. For either version, first
install the dependencies:
* tar :: Required.
* git :: If you want to use development versions of your dependencies.
* sbcl or ccl :: Either is required if systems need to be groveled for
dependencies (likely needed if you use development versions of any
dependency). SBCL is required if you are installing from source.
** Prebuilt binaries
To install CLPM in binary form, download the appropriate file from
[[https://common-lisp.net/project/clpm/downloads/][https://common-lisp.net/project/clpm/downloads/]]. Each release of CLPM
consists of the following files:
+ =clpm-amd64-linux-gnu-$VERSION.tar.gz= :: CLPM compiled for 64bit Linux
using GNU libc (by far the most common).
+ =clpm-amd64-linux-musl-$VERSION.tar.gz= :: CLPM compiled for 64bit Linux
using musl libc (e.g., Alpine Linux).
+ =clpm-arm64-linux-gnu-$VERSION.tar.gz= :: CLPM compiled for 64bit Linux on
ARM processors using GNU libc.
+ =clpm-arm64-linux-musl-$VERSION.tar.gz= :: CLPM compiled for 64bit Linux
on ARM processors using musl libc.
+ =clpm-armv7-linux-gnu-$VERSION.tar.gz= :: CLPM compiled for 32bit Linux on
ARM processors using GNU libc.
+ =clpm-armv7-linux-musl-$VERSION.tar.gz= :: CLPM compiled for 32bit Linux
on ARM processors using musl libc.
+ =clpm-amd64-windows-$VERSION.msi= :: CLPM installer for 64 bit Windows.
+ =clpm-$VERSION.DIGESTS= :: Text file containing the SHA512 sums for every
previously mentioned file.
+ =clpm-$VERSION.DIGESTS.asc= :: Same as =clpm-$VERSION.DIGESTS=, but signed
with GPG key =0x10327DE761AB977333B1AD7629932AC49F3044CE=.
*** GNU/Linux
After downloading the tarball and validating the SHA512 sum, unpack it and
run =sh install.sh=. By default, it is installed to =/usr/local/=, but that
prefix con be changed using the =INSTALL_ROOT= environment
variable. However, if you change the prefix, you will also likely need to
set the =CLPM_HOME= environment variable to point to
=$INSTALL_ROOT/lib/clpm/=.
*** Windows
After downloading the installer and validating the SHA512 sum, simply run
the installer and follow the directions.
** Source Install
See [[file:INSTALL.org][INSTALL]] for more details on installing from source.
* Quickstart
......@@ -45,7 +102,7 @@ files.
:url "https://beta.quicklisp.org/dist/quicklisp.txt")
#+end_src
See [[file:doc/sources.org][sources.org]] for more details on configuring sources.
See [[file:docs/sources.org][sources]] for more details on configuring sources.
Next, configure your favorite Lisp to load the client by placing the output
of the following command in your Lisp's init file (such as =~/.sbclrc=).
......@@ -104,7 +161,7 @@ files.
** Support HTTPS
HTTPS is becoming more and more ubiquitous. Some websites (such as Github
and Gitlab) are only served over HTTPS and some users insist on HTTPS
and Gitlab) are only served over HTTPS and some people insist on HTTPS
everywhere possible. This trend is not going away, therefore CLPM should
natively support HTTPS.
......@@ -145,7 +202,7 @@ files.
live in reality and this happens frequently (just look at the packages that
get removed from Quicklisp in any given release for failing to
build). Additionally, sometimes you just really need to use an old version
of a dependcy for some project while using the latest version of the same
of a dependency for some project while using the latest version of the same
dependency in another project.
To this end, CLPM supports installing multiple versions of the same package
......@@ -172,12 +229,12 @@ files.
For more documentation on CLPM, you may find the following files useful:
+ [[file:doc/client.org][client.org]] :: Summary of CLPM's client.
+ [[file:doc/config.org][config.org]] :: Summary of all of CLPM's configuration options.
+ [[file:doc/sources.org][sources.org]] :: Summary of all supported software repositories.
+ [[file:doc/bundle.org][bundle.org]] :: Information on how to use CLPM to manage and repeatably
+ [[file:docs/client.org][client]] :: Summary of CLPM's client.
+ [[file:docs/config.org][config]] :: Summary of all of CLPM's configuration options.
+ [[file:docs/sources.org][sources]] :: Summary of all supported software repositories.
+ [[file:docs/bundle.org][bundle]] :: Information on how to use CLPM to manage and repeatably
install dependencies for a single project.
+ [[file:doc/storage.org][storage.org]] :: Information on where CLPM writes data to your hard drive.
+ [[file:docs/storage.org][storage]] :: Information on where CLPM writes data to your hard drive.
* Footnotes
......
#+TITLE: CLPM Bundle
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
This file describes the "bundle" capabilities of CLPM. Bundles are anonymous,
project specific contexts that can be included in source repositories.
......@@ -104,7 +105,7 @@ with zero 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.[fn:2]
all explicitly defined systems are required.
*** ~:asd~
......@@ -153,6 +154,9 @@ with zero configuration or helpers needed (other than ASDF, of course).
All environment variables are present in the new process, additionally the
following environment variables are set:
+ =ASDF_OUTPUT_TRANSLATIONS= :: If CLPM is configured to manage the output
translations for bundles. See =:output-translations= in the =(:bundle)=
config table.
+ =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. Used by
......
#+TITLE: CLPM Client
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
While CLPM can be used without the client, installing and using the client
makes Common Lisp coding a more interactive and fun experience. The CLPM client
......
#+TITLE: CLPM Configuration
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil H:9
CLPM can be configured through environment variables or a file named
=clpm.conf=. The =clpm.conf= file is found by constructing a list of
......@@ -46,8 +47,7 @@ to ="/home/user/.config/common-lisp/source-registry.conf.d/50-clpm.conf"=
#+end_src
The following describes the available configuration tables for CLPM. Each
header describes a table (or sub table). The lists in each section describe
that table's keys.
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
......@@ -61,84 +61,118 @@ authenticating to Github, you would set
The current configuration can be printed by running =clpm config info=.
* Root
* =()=
The root table, containing all other tables and some direct options.
+ =:context= :: A string naming the default context.
* =:archives=
** =:tar=
* =(: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=
* =(:bundle)=
This table contains all configuration for operating with bundles.
+ =: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.
** =:local=
*** ="PROJECT-NAME"=
When using the bundle commands, instead of using the upstream git repository
for PROJECT-NAME, use a local checkout instead.
** =(: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
location of the clpmfile.
directory of the clpmfile.
* =:contexts=
** ="CONTEXT-NAME"=
* =(:contexts)=
This table contains configuration for all contexts.
+ =:source-registry.d-files= :: Used to inform ASDF where to find systems
for this context. Outputs the same contents to every file in a format
suitable for inclusion in a source-registry.d directory (see ASDF manual).
** =(:contexts "CONTEXT-NAME")=
This table contains the configuration for context =CONTEXT-NAME=.
+ =:source-registry-files= :: Used to inform ASDF where to find systems for
this context. Outputs the same contents to every file in a
source-registry.conf format (see ASDF manual).
+ =: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=
Settings for the HTTP method that uses the external curl program.
* =(:curl)=
This table contains configuration for using the curl executable as an HTTP
client.
+ =:path= :: Path to the =curl= executable. Defaults to ="curl"=.
* =:firejail=
Settings for the grovel sandbox method that uses the external firejail
program.
* =(: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=
** =:remotes=
*** ="HOSTNAME"=
Provide configuration for interacting with HOSTNAME to fetch git repos.
* =(: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.
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=
** =:sandbox=
Options for configuring the sandbox used to isolate processes that grovel for
dependencies from .asd files. (Experimental)
* =(:grovel)=
This table contains configuration for groveling for dependencies and other
information from .asd files.
** =(: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=
** =:headers=
*** ="HOSTNAME=
**** ="HEADER-NAME"=
When performing a non-git HTTP request to HOSTNAME, provide a header with
the name HEADER-NAME.
* =(: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.
......@@ -148,10 +182,14 @@ The current configuration can be printed by running =clpm config info=.
+ =:contents= :: A path to a file that contains the value to use for the
header. Must be a string or pathname.
* =:http-client=
* =(:http-client)=
This table contains configuration for the internal HTTP client.
+ =:type= :: A keyword specifying which HTTP client to use. Defaults to
=:auto=.
* =:tar=
Settings for the tar archive method that uses the external tar program.
* =(: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"=.
#+TITLE: CLPM Sources
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
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 be extended to
......
#+TITLE: CLPM Storage
#+AUTHOR: CLPM Developers
#+EMAIL: clpm-devel@common-lisp.net
#+OPTIONS: toc:1 num:nil
This document specifies what files on your computer CLPM will touch and why.
......
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