add more useful text to the README

diff --git a/README b/README
index c81fd7887768f4cfd3ea03f04291da03934e6d16..3440af9ff175a664d9060327f3d6a7d398824aa3 100644 (file)
--- a/README
+++ b/README
@@ -2,6 +2,10 @@
 Welcome to the AllMyData "tahoe" project. This project implements a
 scalable distributed fault-tolerant filestore.
 
+The basic idea is that the data in this filesystem is spread over all
+participating nodes, using an algorithm that can recover the data even if a
+majority of the nodes are no longer available.
+
 The main application code is in the 'allmydata' package, under src/allmydata/
 . There is also a patched version of PyCrypto (adding a faster CTR-mode) in
 src/Crypto/ which gets installed to the 'allmydata.Crypto' package (since the
@@ -44,22 +48,63 @@ BUILDING:
 
  'make test' runs the unit test suite.
 
- 'make deb-dapper' or 'make deb-sid' will construct a debian package named
- 'allmydata-tahoe'.
+INSTALLING:
+
+ If you're running on a debian system, use 'make deb-dapper' or 'make
+ deb-sid' to construct a debian package named 'allmydata-tahoe', which you
+ can then install.
+
+ If not, you'll need to run three separate install steps, one for each of the
+ three subpackages (allmydata, allmydata.Crypto, and pyfec). You may wish to
+ use a different version of 'python' for these steps, or provide a --prefix
+ or --root argument for the install.
+
+  cd src/pyfec && python setup.py install && cd ../..
+
+  cd src/Crypto && python setup.py install && cd ../..
+
+  # the allmydata subpackage's setup.py script is in the root directory
+  python setup.py install
+
+ To test that all the modules got installed properly, start a python
+ interpreter and import modules as follows:
+
+  % python
+  Python 2.4.4 (#2, Jan 13 2007, 17:50:26)
+  [GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>> import allmydata.Crypto
+  >>> import allmydata.interfaces
+  >>> import fec
+  >>>
+
+ To run from a source tree (without installing first), type 'make', which
+ will put all the necessary libraries into a local directory named
+ instdir/lib/pythonN.N/site-packages/ , which you can then add to your
+ PYTHONPATH .
+
 
 RUNNING:
 
- If you installed one of the debian packages constructed by "make deb-*" then 
- it creates an 'allmydata-tahoe' executable, usually in /usr/bin . If you 
- didn't install a package you can find allmydata-tahoe in instdir/scripts.  
- This tool is used to create, start, and stop nodes.  
-
- Somewhere in your mesh there must be a central 'queen' node. This is
- constructed by running 'allmydata-tahoe create-queen --basedir WHERE'. Once
- constructed, you can start the queen by running 'allmydata-tahoe start
- --basedir WHERE'. Inside that base directory, there will be a pair of files
- 'introducer.furl' and 'vdrive.furl'. Make a copy of these, as they'll be
- needed on the client nodes.
+ If you installed one of the debian packages constructed by "make deb-*" then
+ it creates an 'allmydata-tahoe' executable, usually in /usr/bin . If you
+ didn't install a package you can find allmydata-tahoe in instdir/scripts.
+ This tool is used to create, start, and stop nodes. Each node lives in a
+ separate base directory, inside of which you can add files to configure and
+ control the node. Nodes also read and write files within that directory.
+
+ A mesh consists of a single central 'queen' node and a large number of
+ 'client' nodes. If you are joining an existing mesh, the queen node will
+ already be running, and you'll just need to create a client node. If you're
+ creating a brand new mesh, you'll need to create both a queen and a client
+ (and then invite other people to create their own client nodes and join your
+ mesh).
+
+ The queen node is constructed by running 'allmydata-tahoe create-queen
+ --basedir WHERE'. Once constructed, you can start the queen by running
+ 'allmydata-tahoe start --basedir WHERE'. Inside that base directory, there
+ will be a pair of files 'introducer.furl' and 'vdrive.furl'. Make a copy of
+ these, as they'll be needed on the client nodes.
 
  To construct a client node, pick a new working directory for it, then run
  'allmydata-tahoe create-client --basedir $HERE'. Copy the two .furl files