contrib/asdf-install/README

   1 Downloads and installs an ASDF system or anything else that looks
   2 convincingly like one, including updating the ASDF:*CENTRAL-REGISTRY*
   3 symlinks for all the toplevel .asd files it contains.  Please read
   4 this file before use: in particular: this is an automatic tool that
   5 downloads and compiles stuff it finds on the 'net.  Please look at the
   6 SECURITY section and be sure you understand the implications
   7
   8
   9 = USAGE
  10
  11 This can be used either from within an SBCL instance:
  12
  13 * (require 'asdf-install)
  14 * (asdf-install:install 'xlunit) ; for example
  15
  16 or standalone from the shell:
  17
  18 $ sbcl-asdf-install xlunit
  19
  20 Each argument may be -
  21
  22  - The name of a cliki page.  asdf-install visits that page and finds
  23    the download location from the `:(package)' tag - usually rendered
  24    as "Download ASDF package from ..."
  25
  26  - A URL, which is downloaded directly
  27
  28  - A local tar.gz file, which is installed
  29
  30
  31 = SECURITY CONCERNS: READ THIS CAREFULLY
  32
  33 When you invoke asdf-install, you are asking SBCL to download,
  34 compile, and install software from some random site on the web.  Given
  35 that it's indirected through a page on CLiki, any malicious third party
  36 doesn't even need to hack the distribution server to replace the
  37 package with something else: he can just edit the link.
  38
  39 For this reason, we strongly recommend that package providers use PGP
  40 or GPG to crypto-sign their packages (see details at the URL in the
  41 PACKAGE CREATION section) and that users check the signatures.
  42 asdf-install makes three checks
  43
  44  1) that the signature exists
  45
  46  2) that there is a GPG trust relationship between the package signer
  47     and the installer (i.e. that the package comes from someone whose
  48     key you've signed, or someone else you have GPG trust with has signed)
  49
  50  3) that the signature is one of the ones listed in
  51     $HOME/.sbcl/trusted-uids.lisp as a valid supplier of Lisp code.
  52
  53
  54 = CUSTOMIZATION
  55
  56 If the file $HOME/.asdf-install exists, it is loaded.  This can be
  57 used to override the default values of exported special variables.
  58 Presently these are
  59
  60 *PROXY*
  61    defaults to $http_proxy environment variable
  62 *CCLAN-MIRROR*
  63    preferred/nearest CCLAN node.  See the list at
  64    http://ww.telent.net/cclan-choose-mirror
  65 *SBCL-HOME*
  66    Set from $SBCL_HOME environment variable.  This should already be
  67    correct for whatever SBCL is running, if it's been installed correctly
  68 *LOCATIONS*
  69    Possible places in the filesystem to install packages into.  See default
  70    value for format
  71
  72
  73 = PACKAGE CREATION
  74
  75 If you want to create your own packages that can be installed using this
  76 loader, see the "Making your package downloadable..." section at
  77 <http://www.cliki.net/asdf-install>
  78
  79
  80 = HACKERS NOTE
  81
  82 Listen very carefully: I will say this only as often as it appears to
  83 be necessary to say it.  asdf-install is not a good example of how to
  84 write a URL parser, HTTP client, or anything else, really.
  85 Well-written extensible and robust URL parsers, HTTP clients, FTP
  86 clients, etc would definitely be nice things to have, but it would be
  87 nicer to have them in CCLAN where anyone can use them - after having
  88 downloaded them with asdf-install - than in SBCL contrib where they're
  89 restricted to SBCL users and can only be updated once a month via SBCL
  90 developers.  This is a bootstrap tool, and as such, will tend to
  91 resist changes that make it longer or dependent on more other
  92 packages, unless they also add to its usefulness for bootstrapping.
  93
  94
  95 = TODO
  96
  97 a) gpg signature checking would be better if it actually checked against
  98 a list of "trusted to write Lisp" keys, instead of just "trusted to be
  99 who they say they are"
 100
 101 e) nice to have: resume half-done downloads instead of starting from scratch
 102 every time.  but right now we're dealing in fairly small packages, this is not
 103 an immediate concern
 104
 105