- pywin32 >= v210 -- required only for Windows (and not for Cygwin)

    DEPENDENCIES:

    If you aren't getting a pre-compiled binary, then you'll have to ensure that
    the following packages are installed before you install Tahoe.

    There are two kinds of dependencies, "manual dependencies" and
    "easy_install-able dependencies".  The latter kind are normally automatically
    satisfied for you when you install Tahoe, but if something goes wrong, please
    see the EASY_INSTALLABLE DEPENDENCIES section below.

    All of the manual dependencies can probably be installed through your
    standard package management tool if you are running on a modern Unix
    operating system.  For example, on an debian-like system, you can do "sudo
    apt-get install build-essential python-dev python-twisted python-pyopenssl".

    The Manual Dependencies:

     + a C compiler (language)

     + GNU make (build tool)

     + Python 2.4 or newer (tested against 2.4.4, and 2.5.1 -- note that 2.4.1 is
       known not to work due to a bug in its base-32 encoder), including
       development headers i.e. "Python.h" (language)

       http://python.org/

     + Twisted Python (tested against 2.2.0, 2.4.0, and 2.5.0) (network and
       operating system integration library)

       http://twistedmatrix.com/

       Installing from the Twisted source tarball works on all known supported
       platforms, including cygwin.

       You need the following subpackages, which are included in the default
       Twisted distribution:

       * core (the standard Twisted package)
       * web, trial, conch

       Twisted requires that you manually install zope.interface, a copy of which
       is included in the Twisted distribution. Note that Twisted does *not*
       require the entire Zope distribution, merely the much smaller
       zope.interface component.

     + OpenSSL, including development headers (cryptography library)

       http://openssl.org

     + Crypto++, including development headers (cryptography library)

       http://cryptopp.com

     + Python PyOpenSSL (0.6 or later) (secure transport layer)

       http://pyopenssl.sourceforge.net

       To install PyOpenSSL on cygwin, install the OpenSSL development libraries
       with the cygwin package management tool, then get the pyOpenSSL source
       code, cd into it, and run "python ./setup.py install".

    xxx

    GETTING THE SOURCE CODE:

    You need the source code if you are going to install The Debian Way, The
    Setuptools Way, or The Running-In-Place Way (see below).  You do not need the
    source code if you are getting precompiled binaries for Debian or Ubuntu (see
    above), or if you are going to install The easy_install Way (see below).

    The code is available via darcs by running the following command:

    darcs get http://allmydata.org/source/tahoe/trunk tahoe

    This will create a directory named "tahoe" in the current working directory
    and put a copy of the latest source code into it.  Later, if you want to get
    any new changes, then cd into that directory and run the command "darcs
    pull".

    Tarballs of sources are available at:

    http://allmydata.org/source/tahoe/

    INSTALLING:

    There are four ways to do it: The easy_install Way, The Setuptools Way, The
    Running-In-Place Way, and The Debian Way.  Choose one.  If you're not sure,
    choose the easy_install way.

     The easy_install Way:

      You don't need to download the source code first.  You do need to have the
      "easy_install" tool installed first:

      http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install

      The 'easy_install' tool can download and install tahoe for you. Just type
      'easy_install allmydata-tahoe' from any shell. That will download the most
      recent Tahoe source tarball, unpack it in a temporary directory, install it
      to the standard location, then download and install any easy_install-able
      dependencies that you need (setuptools, zfec, foolscap, simplejson, nevow,
      and pycryptopp).  (This will work only if you have already installed the
      dependencies listed in the MANUAL DEPENDENCIES section, above.)

      The end result will be that the Tahoe code is installed to the standard
      location for libraries on your operating system (on unix, that is somewhere
      inside /usr/lib/), and the "tahoe" executable will be installed to the
      standard location for executables on operating system.

     The Setuptools Way:

      Get the source code (see above).

      Run 'python setup.py install'. This will compile and install the Tahoe code
      to the standard location for your operating system (on unix, that is
      somewhere inside /usr/lib/). It will also acquire and install the
      easy_install-able dependencies (setuptools, zfec, foolscap, simplejson,
      nevow, and pycryptopp) to the same place.  (This will work only if you have
      already installed the dependencies listed in the MANUAL DEPENDENCIES
      section, above.)

      (To install it to a non-standard location, see
      http://allmydata.org/trac/tahoe/wiki/SetuptoolsAndGNUStow .)

      The end result will be that the Tahoe code is installed to the standard
      location for libraries on your operating system (on unix, that is somewhere
      inside /usr/lib/), and the "tahoe" executable will be installed to the
      standard location for executables on operating system.

     The Running-In-Place Way:

      You can use Tahoe without installing it.  The steps are these:

      1. Get the source code (see above).

      2. Run "make build-auto-deps" to install the easy_install-able dependencies
         (setuptools, zfec, foolscap, simplejson, nevow, and pycryptopp) into a
         local subdirectory of the Tahoe source distribution. (Note that when the
         dependent libraries are updated, you should use "make clean" before
         "make build-auto-deps" to make sure you will get the newest versions).

      3. Build Tahoe by running "make".

      4. Once you've built it then you can execute "./bin/tahoe". (When the tahoe
         script is in a Tahoe source distribution, it adds the necessary
         directory to the Python "sys.path". It also looks for any dependencies
         that you installed by "make build-auto-deps" and includes them in the
         sys.path.) See the RUNNING section, below.

     The Debian Way:

      The Debian Way is to build .deb files which you can then install with
      "dpkg".

      This requires certain debian packages (build-essential, fakeroot,
      devscripts, debhelper, cdbs) to be installed first, since they are used to
      construct the Tahoe .deb files. A full list of these required packages can
      be found in the "Build-Depends" line in the misc/DIST/debian/control in the
      top-level tahoe directory (replacing the word DIST with etch, dapper, edgy,
      or feisty as appropriate).

      Get the source code (see above).

      If you're running on a debian system, run 'make deb-etch', 'make deb-sid',
      'make deb-edgy', or 'make deb-feisty' from within the tahoe top-level
      directory to construct a debian package named 'allmydata-tahoe' which you
      can then install with dpkg.

    TESTING THAT IT IS PROPERLY INSTALLED

     If you have gotten the source code, then you can run 'make check-deps'
     checks that all of the required Python package dependencies are installed.
     You can run 'make test' runs the unit test suites.  (This can take a long
     time on slow computers.  There are a lot of tests and some of them do a lot
     of public-key cryptography.)

     Executing the tahoe script from the "bin" subdirectory will work only if
     Tahoe itself is installed, either because it is installed into the local
     subdirectory (as per "The Running-In-Place Way") or because it is installed
     into your system (as per the other three ways of installing).

    RUNNING:

     Run the "tahoe" executable.

     If you installed "The Running-In-Place Way", then it is in your source tree,
     in the "bin" subdirectory thereof.  If you installed in one of the other
     three ways, then it has been installed into your operating system's
     filesystem, perhaps in "/usr/bin" on Unix, or in "C:\Python25\Scripts" on
     Window.

     The "tahoe" utility 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 grid consists of a single central 'introducer and vdrive' node and one or
     more 'client' nodes.  If you are joining an existing grid, the
     introducer-and-vdrive node will already be running, and you'll just need to
     create a client node.  If you're creating a brand new grid, you'll need to
     create both an introducer-and-vdrive and a client (and then invite other
     people to create their own client nodes and join your grid).

     The introducer (-and-vdrive) node is constructed by running 'tahoe
     create-introducer --basedir $HERE'. Once constructed, you can start the
     introducer by running 'tahoe start --basedir $HERE' (or, if you are already
     in the introducer's base directory, just type 'tahoe start'). 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 want to use a publically available test grid, get the
     introducer.furl and vdrive.furl files from
     http://allmydata.org/trac/tahoe/wiki/TestGrid instead of running your own
     introducer.)

     To construct a client node, pick a new working directory for it, then run
     'tahoe create-client --basedir $HERE'. Copy the two .furl files from the
     introducer into this new directory, then run 'tahoe start --basedir $HERE'.
     After that, the client node should be off and running. The first thing it
     will do is connect to the introducer and introduce itself to all other nodes
     on the grid. You can follow its progress by looking at the
     $HERE/logs/twistd.log file.

     create-client will put port specification into a file named $HERE/webport,
     unless overridden by the --webport option to create-client. The presence of
     a port specification in the webport file prompts the client node to run a
     webserver on the desired port, through which you can view, upload, download,
     and delete files. The contents of the webport file is actually a "strports
     specification", defined in
     http://twistedmatrix.com/documents/current/api/twisted.application.strports.html
     , so you can have it only listen on a local interface by writing
     "tcp:8123:interface=127.0.0.1" to this file (that's what create-client does
     by default), or make it use SSL by writing
     "ssl:8123:privateKey=mykey.pem:certKey=cert.pem" instead.

     A client node directory can also be created without installing the code
     first.  Just use 'make create-client', and a new directory named 'CLIENTDIR'
     will be created inside the top of the source tree.  Copy the relevant .furl
     files in, set the webport, then start the node by using 'make start-client'.
     To stop it again, use 'make stop-client'.  Similar makefile targets exist
     for making and running an introducer node.

     If you are behind a firewall and you can configure your firewall to forward
     TCP connections on a port to the computer running your Tahoe node, then you
     can configure the Tahoe node to announce itself as being available on that
     IP address and port.  The way to do this is to create a file named
     $HERE/advertised_ip_addresses, in which you can put IP addresses and port
     numbers in "dotted-quad:port" form, e.g. "209.97.232.113:1345".  You can put
     multiple IP-address-and-port-number entries into this file, on separate
     lines.

     There is a public grid available for testing. The necessary .furl files are
     in docs/testgrid/*.furl . More information is available on
     http://allmydata.org/trac/tahoe/wiki/TestGrid .

The code is retrievable using the darcs revision control tool by running the following command:

    darcs get http://allmydata.org/source/tahoe/trunk tahoe

This will create a directory named

    tahoe

in the current working directory and put a copy of the latest source code into it. Later, if you want to get any new changes, then cd into that directory and run the command

    darcs pull

.

`operating system` location of
    tahoe
executable `linux` |
    /usr/bin
`cygwin` |
    /usr/bin
`Windows` |
    C:\Python25\Scripts
`Mac OS X` |
    /Frameworks/Python/Versions/2.5/binpre>(XXX double-check this)
`Solaris` |
    /usr/bin
(XXX double-check this)

     + Python setuptools (build and distribution tool) >= v0.6c6

       http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions

       The Tahoe install process will automatically use its own bundled copy
       setuptools if a sufficiently new version of setuptools is not installed on
       the system.  Unlike It will not install it into the system -- this is a build
       dependency, not an install dependency.

    EASY_INSTALLABLE DEPENDENCIES

    The following Python packages are required, but they are bundled with Tahoe (in
    the misc/dependencies directory), and are built by make
    build-auto-deps.  If you install Tahoe using The Setuptools Way or The
    easy_install Way then these packages will automatically be installed along with
    Tahoe.

     + zfec (erasure coding library) >= v1.3.0

       http://cheeseshop.python.org/pypi/zfec

     + foolscap (secure remote object library) >= v0.2.3

       http://cheeseshop.python.org/pypi/foolscap

     + simplejson (JSON parser) >= v1.7.3

       http://cheeseshop.python.org/pypi/simplejson

     + nevow (web presentation language) >= v0.6.0

       http://divmod.org/trac/wiki/DivmodNevow

       Note that Nevow >= v0.9.18 requires Twisted >= v2.4.0.  If you are on Ubuntu 6.06 ("dapper") or Debian 3.1 ("sarge"), this means you have to install Twisted >= v2.4.0 yourself, or else install Nevow v0.6.0 in egg form yourself (e.g. run easy_install nevow == 0.6.0).

     + pycryptopp (Python crypto library) >= v0.2.9

       http://pypi.python.org/pypi/pycryptopp

     + zope.interface (programming language extensions) >= v3.1.0

       http://pypi.python.org/pypi/pycryptopp

       Tahoe does not require the entire Zope package, merely
       the much smaller zope.interface component.

    xxx
    If you are behind a firewall and you can configure your firewall to
    forward TCP connections on a port to the computer running your Tahoe
    node, then you can configure the Tahoe node to announce itself as
    being available on that IP address and port.  The way to do this is to
    create a file named $HERE/advertised_ip_addresses, in which you can
    put IP addresses and port numbers in "dotted-quad:port" form,
    e.g. "209.97.232.113:1345".  You can put multiple
    IP-address-and-port-number entries into this file, on separate lines.