1.0.0.15: build fix & cleanup
[sbcl.git] / 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