viff

changeset 700:4df225223500

Added installation guide.
author Martin Geisler <mg@daimi.au.dk>
date Tue, 22 Apr 2008 08:46:45 +0200
parents acfa9aa5bd59
children 2acd3ae55565
files doc/index.txt doc/install.txt
diffstat 2 files changed, 240 insertions(+), 0 deletions(-) [+]
line diff
     1.1 --- a/doc/index.txt	Tue Apr 22 08:38:25 2008 +0200
     1.2 +++ b/doc/index.txt	Tue Apr 22 08:46:45 2008 +0200
     1.3 @@ -12,6 +12,7 @@
     1.4     :maxdepth: 2
     1.5  
     1.6     overview
     1.7 +   install
     1.8     glossary
     1.9  
    1.10  
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/install.txt	Tue Apr 22 08:46:45 2008 +0200
     2.3 @@ -0,0 +1,239 @@
     2.4 +.. -*- coding: utf-8 -*-
     2.5 +.. (Links are marked with underscores, see the bottom of the file.)
     2.6 +
     2.7 +====================
     2.8 + Installation Guide
     2.9 +====================
    2.10 +
    2.11 +VIFF is written in Python and uses the Twisted framework for
    2.12 +asynchronous communication, (optionally) python-gnutls for secure
    2.13 +communication, ConfigObj for configuration files, and GMPY for fast
    2.14 +bignum arithmetic. You can find these components here:
    2.15 +
    2.16 +:Python:         http://python.org/
    2.17 +:Twisted:        http://twistedmatrix.com/
    2.18 +:python-gnutls:  http://pypi.python.org/pypi/python-gnutls/
    2.19 +:ConfigObj:      http://voidspace.org.uk/python/configobj.html
    2.20 +:GMPY:           http://code.google.com/p/gmpy/
    2.21 +
    2.22 +VIFF has been successfully tested with the following versions:
    2.23 +
    2.24 +:Python:         2.4.1 and 2.5.0
    2.25 +:Twisted:        2.5.0
    2.26 +:python-gnutls:  1.1.4
    2.27 +:ConfigObj:      4.4.0
    2.28 +:GMPY:           1.0alpha and 1.0.2
    2.29 +
    2.30 +Please `report back`_ if you find that VIFF works with other versions
    2.31 +than the ones listed here.
    2.32 +
    2.33 +Below you will find installation instructions for the different
    2.34 +platforms on which we `test VIFF`_.
    2.35 +
    2.36 +
    2.37 +Windows
    2.38 +-------
    2.39 +
    2.40 +This describes installation of VIFF on Windows XP Professional Version
    2.41 +2002 SP2.
    2.42 +
    2.43 +1) Download and install Python_.
    2.44 +
    2.45 +2) Include the path to your Python installation (e.g. ``C:\Python25\``)
    2.46 +   in the ``PATH`` system environment variable. One way to edit this
    2.47 +   environment variable is by right-clicking My Computer in the Start
    2.48 +   menu, selecting Properties, Advanced, and then pressing the
    2.49 +   Environment Variables button.
    2.50 +
    2.51 +3) Download and install Twisted_.
    2.52 +
    2.53 +4) Download ConfigObj_ and enter::
    2.54 +
    2.55 +      python setup.py install
    2.56 +
    2.57 +   from the folder where you unzipped the files.
    2.58 +
    2.59 +5) Download and install GMPY_.
    2.60 +
    2.61 +6) In order to secure the channels between the players using TLS, you
    2.62 +   need to download and install python-gnutls_. However, we haven't
    2.63 +   had the time to test installation of this on Windows yet. Feel free
    2.64 +   to contribute with details about this by sending an email to the
    2.65 +   `VIFF mailing list`_.
    2.66 +
    2.67 +7) Proceed to `testing`_.
    2.68 +
    2.69 +
    2.70 +Mac OS X
    2.71 +--------
    2.72 +
    2.73 +This describes installation of VIFF on Max OS X 10.5.
    2.74 +
    2.75 +1) Download and install the full MacPython_ version 2.5 (the
    2.76 +   Python-installation which comes with Mac OS X is not entirely
    2.77 +   up-to-date).
    2.78 +
    2.79 +2) Download and Install Twisted_ from source. Notice again that Mac OS
    2.80 +   X comes with a pre-installed version of Twisted, but this is not
    2.81 +   the full Twisted installation. After installation change your
    2.82 +   ``PYTHONPATH`` (in your ``~/.bash_profile``) to::
    2.83 +
    2.84 +      PATH="/Library/Python/2.5/site-packages:${PATH}"
    2.85 +
    2.86 +3) You can skip this step if you do not want secure connections.
    2.87 +   Otherwise install python-gnutls_:
    2.88 +
    2.89 +   a) Install XCode_ from Apple which provides the GCC compiler.
    2.90 +   b) Install gnutls_ (and required packages) from source.
    2.91 +   c) Install python-gnutls_.
    2.92 +
    2.93 +4) Download ConfigObj_ and enter::
    2.94 +
    2.95 +      python setup.py install
    2.96 +
    2.97 +   from the folder where you unzipped the files.
    2.98 +
    2.99 +5) Download and install GMPY_ following the instructions in
   2.100 +   ``gmpy-1.02.macosx.README.txt`` (under Downloads).
   2.101 +
   2.102 +6) Install VIFF from source (see below). If you prefer you can just
   2.103 +   install it in site-packages, it makes no difference. For
   2.104 +   developers, it is perhaps a better solution in to create a symbolic
   2.105 +   link from the site-packages directory to the VIFF Python files
   2.106 +   (``viff/viff/``), as otherwise you need to re-install VIFF each time
   2.107 +   the project is modified.
   2.108 +
   2.109 +7) Proceed to `testing`_.
   2.110 +
   2.111 +
   2.112 +GNU/Linux
   2.113 +---------
   2.114 +
   2.115 +VIFF was originally developed on GNU/Linux and is well supported
   2.116 +there. When installing the VIFF dependencies you either have the
   2.117 +option of using your `package manager`_ or to install from source. VIFF
   2.118 +itself must be installed `from source`_.
   2.119 +
   2.120 +
   2.121 +Using a Package Manager
   2.122 +~~~~~~~~~~~~~~~~~~~~~~~
   2.123 +
   2.124 +Debian Lenny (testing)
   2.125 +  You can install all dependencies by the command::
   2.126 +
   2.127 +     aptitude install python-twisted-core python-gnutls \
   2.128 +                      python-configobj python-gmpy
   2.129 +
   2.130 +  The backslash indicates that both lines should be typed as a single
   2.131 +  line in the terminal.
   2.132 +
   2.133 +Ubuntu
   2.134 +  We expect that the instructions for Debian also apply here.
   2.135 +
   2.136 +
   2.137 +If you know how to install using other package managers, please `let
   2.138 +us know`_.
   2.139 +
   2.140 +VIFF itself is not yet packaged for any distribution, so you will have
   2.141 +to install it from source as described below.
   2.142 +
   2.143 +
   2.144 +Installing from Source
   2.145 +~~~~~~~~~~~~~~~~~~~~~~
   2.146 +
   2.147 +If you do not have permission to use the package manager or simply
   2.148 +prefer to install from source, then (assuming that Python is already
   2.149 +installed) one can easily install VIFF and its dependencies by
   2.150 +downloading and unpacking each of them and executing::
   2.151 +
   2.152 +   python setup.py install --home=$HOME/opt
   2.153 +
   2.154 +That will install everything under the given prefix. With the above
   2.155 +command the Python modules are installed into::
   2.156 +
   2.157 +   $HOME/opt/lib/python
   2.158 +
   2.159 +and some programs are installed into::
   2.160 +
   2.161 +   $HOME/opt/bin
   2.162 +
   2.163 +You should add the first directory to the ``PYTHONPATH`` environment
   2.164 +variable and the latter to the ``PATH`` environment variable.
   2.165 +
   2.166 +Bash uses can normally do this by adding::
   2.167 +
   2.168 +   export PYTHONPATH=$PYTHONPATH:$HOME/opt/lib/python
   2.169 +   export PATH=$PATH:$HOME/opt/bin
   2.170 +
   2.171 +to their ``~/.bash_profile`` file, creating it if it is not already
   2.172 +there. Consult the documentation for your shell to learn how
   2.173 +environment variables are set.
   2.174 +
   2.175 +
   2.176 +Testing
   2.177 +-------
   2.178 +
   2.179 +To verify the installation, try out one of the applications. We will
   2.180 +run the millionaires example with three players and a threshold of
   2.181 +one. For this test, we will let all players run on localhost: Player 1
   2.182 +will run on port 9001, player 2 on port 9002, and player 3 on port
   2.183 +9003. The test is done on Windows, but it works the same on the other
   2.184 +platforms. Do the following:
   2.185 +
   2.186 +1) Go to the ``viff/apps/`` directory and generate the needed
   2.187 +   configuration files by entering::
   2.188 +
   2.189 +     python generate-config-files.py -n 3 -t 1
   2.190 +     localhost:9001 localhost:9002 localhost:9003
   2.191 +
   2.192 +   Both lines should be entered as a single line.
   2.193 +
   2.194 +2) Open three separate command prompts and go to the ``viff/apps/``
   2.195 +   directory in each. In the first, type::
   2.196 +
   2.197 +     python millionaires.py --no-tls player-3.ini
   2.198 +
   2.199 +   in the second, type::
   2.200 +
   2.201 +     python millionaires.py --no-tls player-2.ini
   2.202 +
   2.203 +   and in the last, type::
   2.204 +
   2.205 +     python millionaires.py --no-tls player-1.ini
   2.206 +
   2.207 +   Note that the order in wich you start the players is important: The
   2.208 +   players must start in reverse order, e.g. the last player first. If
   2.209 +   the installation works, you should see something like this from
   2.210 +   e.g. player 3::
   2.211 +
   2.212 +      C:\viff\apps> python millionaires.py --no-tls player-3.ini 
   2.213 +      Seeding random generator with random seed 7416
   2.214 +      Not using TLS
   2.215 +      I am Millionaire 3 and I am worth 20 millions.
   2.216 +      From poorest to richest:
   2.217 +        Millionaire 2
   2.218 +        Millionaire 3 (20 millions)
   2.219 +        Millionaire 1
   2.220 +      Initiating shutdown sequence.
   2.221 +
   2.222 +   If something went wrong, then please `file a bug report`_ or report
   2.223 +   it on the `VIFF mailing list`_. This will help us improve VIFF.
   2.224 +
   2.225 +
   2.226 +.. _report back:
   2.227 +.. _VIFF mailing list:
   2.228 +.. _let us know: viff-devel@viff.dk
   2.229 +
   2.230 +.. _test VIFF: http://buildbot.viff.dk/
   2.231 +.. _Python: http://python.org/
   2.232 +.. _Twisted: http://twistedmatrix.com/
   2.233 +.. _ConfigObj: http://voidspace.org.uk/python/configobj.html
   2.234 +.. _GMPY: http://code.google.com/p/gmpy/
   2.235 +.. _python-gnutls: http://pypi.python.org/pypi/python-gnutls/
   2.236 +.. _MacPython: http://www.pythonmac.org
   2.237 +.. _XCode: http://developer.apple.com/tools/xcode/
   2.238 +.. _gnutls: http://www.gnu.org/software/gnutls/manual/gnutls.html
   2.239 +            #Downloading-and-Installing
   2.240 +.. _package manager: `Using a Package Manager`_
   2.241 +.. _from source: `Installing from Source`_
   2.242 +.. _file a bug report: http://tracker.viff.dk/