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 encourage package providers to crypto-sign their
  40 packages (see details at the URL in the PACKAGE CREATION section) and
  41 users to check the signatures.  asdf-install has three levels of
  42 automatic signature checking: "on", "off" and "unknown sites", which
  43 can be set using the configuration variables described in
  44 CUSTOMIZATION below.  The default is "unknown sites", which will
  45 expect a GPG signature on all downloads except those from
  46 presumed-good sites.  The current default presumed-good sites are
  47 CCLAN nodes, and two web sites run by SBCL maintainers: again, see
  48 below for customization details
  49
  50
  51 = CUSTOMIZATION
  52
  53 If the file $HOME/.asdf-install exists, it is loaded.  This can be
  54 used to override the default values of exported special variables.
  55 Presently these are
  56
  57 *PROXY*
  58    defaults to $http_proxy environment variable
  59 *CCLAN-MIRROR*
  60    preferred/nearest CCLAN node.  See the list at
  61    http://ww.telent.net/cclan-choose-mirror
  62 *SBCL-HOME*
  63    Set from $SBCL_HOME environment variable.  This should already be
  64    correct for whatever SBCL is running, if it's been installed correctly
  65 *VERIFY-GPG-SIGNATURES*
  66    Verify GPG signatures for the downloaded packages?
  67    NIL - no, T - yes, :UNKNOWN-LOCATIONS - only for URLs which aren't in CCLAN
  68    and don't begin with one of the prefixes in *SAFE-URL-PREFIXES*
  69 *LOCATIONS*
  70    Possible places in the filesystem to install packages into.  See default
  71    value for format
  72 *SAFE-URL-PREFIXES*
  73    List of locations for which GPG signature checking /won't/ be done when
  74    *verify-gpg-signatures* is :unknown-locations
  75
  76
  77 = PACKAGE CREATION
  78
  79 If you want to create your own packages that can be installed using this
  80 loader, see the "Making your package downloadable..." section at
  81 <http://www.cliki.net/asdf-install>
  82
  83
  84 = HACKERS NOTE
  85
  86 Listen very carefully: I will say this only as often as it appears to
  87 be necessary to say it.  asdf-install is not a good example of how to
  88 write a URL parser, HTTP client, or anything else, really.
  89 Well-written extensible and robust URL parsers, HTTP clients, FTP
  90 clients, etc would definitely be nice things to have, but it would be
  91 nicer to have them in CCLAN where anyone can use them - after having
  92 downloaded them with asdf-install - than in SBCL contrib where they're
  93 restricted to SBCL users and can only be updated once a month via SBCL
  94 developers.  This is a bootstrap tool, and as such, will tend to
  95 resist changes that make it longer or dependent on more other
  96 packages, unless they also add to its usefulness for bootstrapping.
  97
  98
  99 = TODO
 100
 101 a) gpg signature checking would be better if it actually checked against
 102 a list of "trusted to write Lisp" keys, instead of just "trusted to be
 103 who they say they are"
 104
 105 e) nice to have: resume half-done downloads instead of starting from scratch
 106 every time.  but right now we're dealing in fairly small packages, this is not
 107 an immediate concern
 108
 109