doc/sbcl-asdf-install.1

   1 .TH SBCL\-ASDF\-INSTALL 1 "$Date$"
   2 .AT 3
   3 .SH NAME
   4 .BI SBCL\-ASDF\-INSTALL
   5  -- Download and Install ASDF Systems
   6
   7 .SH SYNOPSIS
   8 .BI sbcl\-asdf\-install
   9 [packages ...]
  10
  11 Each argument may be
  12 .TP 3
  13 \--
  14 The name of a cliki page.  asdf\-install visits that page and finds
  15 the download location from the `:(package)' tag - usually rendered
  16 as "Download ASDF package from ..."
  17 .TP 3
  18 \--
  19 A URL, which is downloaded directly
  20 .TP 3
  21 \--
  22 A local tar.gz file, which is installed
  23
  24
  25 .SH DESCRIPTION
  26 Downloads and installs an ASDF system or anything else that looks
  27 convincingly like one, including updating the ASDF:*CENTRAL\-REGISTRY*
  28 symlinks for all the toplevel .asd files it contains.  Please read
  29 this file before use: in particular: this is an automatic tool that
  30 downloads and compiles stuff it finds on the 'net.  Please look at the
  31 SECURITY section and be sure you understand the implications
  32
  33
  34 .SH SECURITY CONCERNS: READ THIS CAREFULLY
  35 When you invoke asdf\-install, you are asking SBCL to download,
  36 compile, and install software from some random site on the web.  Given
  37 that it's indirected through a page on CLiki, any malicious third party
  38 doesn't even need to hack the distribution server to replace the
  39 package with something else: he can just edit the link.
  40
  41 For this reason, we encourage package providers to crypto-sign their
  42 packages (see details at the URL in the PACKAGE CREATION section) and
  43 users to check the signatures.  asdf\-install has three levels of
  44 automatic signature checking: "on", "off" and "unknown sites", which
  45 can be set using the configuration variables described in
  46 CUSTOMIZATION below.  The default is "unknown sites", which will
  47 expect a GPG signature on all downloads except those from
  48 presumed-good sites.  The current default presumed-good sites are
  49 CCLAN nodes, and two web sites run by SBCL maintainers: again, see
  50 below for customization details
  51
  52
  53 .SH CUSTOMIZATION
  54
  55 If the file $HOME/.asdf\-install exists, it is loaded.  This can be
  56 used to override the default values of exported special variables.
  57 Presently these are
  58 .TP 3
  59 \--
  60 *PROXY*
  61
  62 defaults to $http_proxy environment variable
  63 .TP 3
  64 \--
  65 *CCLAN\-MIRROR*
  66
  67 preferred/nearest CCLAN node.  See the list at
  68 http://ww.telent.net/cclan\-choose\-mirror
  69 .TP 3
  70 \--
  71 *SBCL\-HOME*
  72
  73 Set from $SBCL_HOME environment variable.  This should already be
  74 correct for whatever SBCL is running, if it's been installed correctly
  75 .TP 3
  76 \--
  77 *VERIFY\-GPG\-SIGNATURES*
  78
  79 Verify GPG signatures for the downloaded packages?
  80
  81 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*
  82 .TP 3
  83 \--
  84 *LOCATIONS*
  85
  86 Possible places in the filesystem to install packages into.  See default
  87 value for format
  88 .TP 3
  89 \--
  90 *SAFE\-URL\-PREFIXES*
  91
  92 List of locations for which GPG signature checking won't be done when
  93 *verify\-gpg\-signatures* is :unknown\-locations
  94
  95
  96 .SH PACKAGE CREATION
  97
  98 If you want to create your own packages that can be installed using this
  99 loader, see the "Making your package downloadable..." section at
 100 <http://www.cliki.net/asdf\-install>
 101
 102
 103 .SH HACKERS NOTE
 104
 105 Listen very carefully: I will say this only as often as it appears to
 106 be necessary to say it.  asdf\-install is not a good example of how to
 107 write a URL parser, HTTP client, or anything else, really.
 108 Well-written extensible and robust URL parsers, HTTP clients, FTP
 109 clients, etc would definitely be nice things to have, but it would be
 110 nicer to have them in CCLAN where anyone can use them - after having
 111 downloaded them with asdf\-install - than in SBCL contrib where they're
 112 restricted to SBCL users and can only be updated once a month via SBCL
 113 developers.  This is a bootstrap tool, and as such, will tend to
 114 resist changes that make it longer or dependent on more other
 115 packages, unless they also add to its usefulness for bootstrapping.
 116
 117
 118 .SH TODO
 119
 120 .TP 3
 121 a)
 122 gpg signature checking would be better if it actually checked against
 123 a list of "trusted to write Lisp" keys, instead of just "trusted to be
 124 who they say they are"
 125 .TP 3
 126 b)
 127 nice to have: resume half-done downloads instead of starting from scratch
 128 every time.  but right now we're dealing in fairly small packages, this is not
 129 an immediate concern
 130
 131
 132 .SH SEE ALSO
 133 .BR sbcl (1)