source: trunk/abcl/contrib/asdf-install/README @ 12487

Last change on this file since 12487 was 12487, checked in by Mark Evenson, 12 years ago

Port of ASDF-INSTALL under 'contrib/asdf-install'.

'abcl.contrib' will package ASDF-INSTALL in dist/abcl-contrib.jar.

We only have one contrib 'asdf-install'. It is not expected to work
well under Windows at the moment.

To use ASDF-INSTALL, use the following in your ~/.abclrc:

(require 'asdf)
(pushnew "jar:file:${dist.dir}/abcl-contrib.jar!/asdf-install/" asdf:*central-registry*)

Then issuing

CL-USER> (require 'asdf-install)

will load ASDF-INSTALL.

A file ~/.asdf-install can contain customizations to help ASDF-INSTALL
find the programs 'tar' and 'gpg'. 'tar' is searched for in
asdf-install:*shell-search-paths*. The location of 'gpg' can be
customized by setting *gpg-command* to a string containing the file.
This behavior should be rationalized in the future.

ASDF-INSTALL tested under OSX.

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