source: branches/streams/abcl/contrib/asdf-install/README

Downloads and installs an ASDF or a MK:DEFSYSTEM system or anything
else that looks convincingly like one. It updates the
ASDF:*CENTRAL-REGISTRY* symlinks for all the toplevel .asd files it
contains, and it also MK:ADD-REGISTRY-LOCATION for the appropriate
directories for MK:DEFSYSTEM.

Please read this file before use: in particular: this is an automatic
tool that downloads and compiles stuff it finds on the 'net.  Please
look at the SECURITY section and be sure you understand the
implications


= USAGE

This can be used either from within a CL implementation:

cl-prompt> (load "/path/to/load-asdf-install.lisp")
cl-prompt> (asdf-install:install 'xlunit) ; for example

With SBCL you can also use the standalone command `sbcl-asdf-install'
from the shell:

$ sbcl-asdf-install xlunit


Each argument may be -

 - The name of a cliki page.  asdf-install visits that page and finds
   the download location from the `:(package)' tag - usually rendered
   as "Download ASDF package from ..."

 - A URL, which is downloaded directly

 - A local tar.gz file, which is installed


= SECURITY CONCERNS: READ THIS CAREFULLY

When you invoke asdf-install, you are asking your CL implementation to
download, compile, and install software from some random site on the
web.  Given that it's indirected through a page on CLiki, any
malicious third party doesn't even need to hack the distribution
server to replace the package with something else: he can just edit
the link.

For this reason, we encourage package providers to crypto-sign their
packages (see details at the URL in the PACKAGE CREATION section) and
users to check the signatures.  asdf-install has three levels of
automatic signature checking: "on", "off" and "unknown sites", which
can be set using the configuration variables described in
CUSTOMIZATION below.  The default is "unknown sites", which will
expect a GPG signature on all downloads except those from
presumed-good sites.  The current default presumed-good sites are
CCLAN nodes, and two web sites run by SBCL maintainers: again, see
below for customization details


= CUSTOMIZATION

If the file $HOME/.asdf-install exists, it is loaded.  This can be
used to override the default values of exported special variables.
Presently these are 

*PROXY*         
   defaults to $http_proxy environment variable
*CCLAN-MIRROR*        
   preferred/nearest CCLAN node.  See the list at 
   http://ww.telent.net/cclan-choose-mirror
*ASDF-INSTALL-DIRS*
   Set from ASDF_INSTALL_DIR environment variable.  If you are running
   SBCL, then *ASDF-INSTALL-DIRS* may be set form the environment variable
   SBCL_HOME, which should already be correct for whatever SBCL is
   running, if it's been installed correctly.  This is done for
   backward compatibility with SBCL installations.
*SBCL-HOME*
   This is actually a symbol macro for *ASDF-INSTALL-DIRS*
*VERIFY-GPG-SIGNATURES*
   Verify GPG signatures for the downloaded packages?
   NIL - no, T - yes, :UNKNOWN-LOCATIONS - only for URLs which aren't in CCLAN
   and don't begin with one of the prefixes in *SAFE-URL-PREFIXES*
*LOCATIONS*
   Possible places in the filesystem to install packages into.  See default
   value for format
*SAFE-URL-PREFIXES* 
   List of locations for which GPG signature checking /won't/ be done when
   *verify-gpg-signatures* is :unknown-locations


= PACKAGE CREATION

If you want to create your own packages that can be installed using this
loader, see the "Making your package downloadable..." section at
<http://www.cliki.net/asdf-install> 


= HACKERS NOTE

Listen very carefully: I will say this only as often as it appears to
be necessary to say it.  asdf-install is not a good example of how to
write a URL parser, HTTP client, or anything else, really.
Well-written extensible and robust URL parsers, HTTP clients, FTP
clients, etc would definitely be nice things to have, but it would be
nicer to have them in CCLAN where anyone can use them - after having
downloaded them with asdf-install - than in SBCL contrib where they're
restricted to SBCL users and can only be updated once a month via SBCL
developers.  This is a bootstrap tool, and as such, will tend to
resist changes that make it longer or dependent on more other
packages, unless they also add to its usefulness for bootstrapping.


= TODO

a) gpg signature checking would be better if it actually checked against
a list of "trusted to write Lisp" keys, instead of just "trusted to be
who they say they are"

e) nice to have: resume half-done downloads instead of starting from scratch
every time.  but right now we're dealing in fairly small packages, this is not
an immediate concern