= Additional Build/Install Documentation =

Hopefully, the basic install docs in
[http://allmydata.org/source/tahoe/trunk/docs/install.html docs/install.html]
are enough for the most common use cases. This page provides additional
information for specific platforms.

Please feel free to add sections to this page with anything you might learn
while building Tahoe on other platforms. Information which may be useful in
the most general cases will be folded into docs/install.html .

== Dependencies ==

The canonical list of dependencies and their versions is in [source:_auto_deps.py]. To see the current versions of those dependencies (plus a few others like the Python interpreter and the operating system) run {{{tahoe --version}}}.

This isn't a complete list of dependencies though, because some of those packages also have dependencies of their own. To see the complete list of all dependencies, run {{{PYTHONPATH=${PYTHONPATH}:./support/lib/python2.5/site-packages/ python -c "import pkg_resources;print ', '.join([d.project_name+': '+d.version for d in set(pkg_resources.require('allmydata-tahoe'))])"}}}.  An example output from that command is: 

`zope.interface: 3.5.0, simplejson: 2.0.7, pyutil: 1.3.30, zbase32: 1.1.1, allmydata-tahoe: 1.2.0-r3353, pyOpenSSL: 0.7, Twisted: 8.1.0-r25700, Nevow: 0.9.33-r17166, foolscap: 0.3.2, zfec: 1.4.2, pycryptopp: 0.5.12, argparse: 0.8.0, setuptools: 0.6c10dev`

In addition to these, if you are installing on Microsoft Windows, then you need to manually install [http://sourceforge.net/projects/pywin32 pywin32] before installing Tahoe.

== Overview ==

Tahoe is happy to build and run in-place, from a source tree. It is not
necessary to install it (outside the source tree) before use, but if you'd
like to do so, please read the "Installing Outside The Source Tree" section
below.

However, it does need to be "built" before running it in place. While Tahoe
itself is pure-python and therefore does not require a distinct compile step,
the mechanics that make it easy to run-in-place do require a setup phase. In
addition, Tahoe uses several third-party python libraries to work its magic,
many of which are unlikely to be just "lying around" and already installed.
Several of these use compiled C code, so they '''do''' require a compile
step.

The "make all" target will download and build any third-party libraries that
are not already available on your system. It will also prepare the source
tree for running-in-place. The details: this target is equivalent to
executing "{{{setup.py build_tahoe}}}", and basically does a
"{{{setup.py develop}}}" into a tree-local
{{{./support/lib/python2.5/site-packages/}}} directory. The {{{bin/tahoe}}}
executable knows that it should add this directory to PYTHONPATH before it
does anything else.

After building, you can run the source tree's {{{bin/tahoe}}} script to
create, configure, and use your new Tahoe node. As long as {{{bin/tahoe}}} is
left inside the built source tree, it can be run from anywhere (even through a
symlink). So until you delete the source tree, you can
symlink {{{~/bin/tahoe}}} to your source tree's {{{bin/tahoe}}} and then use
it as you would any other system executable.

== the "Desert Island" Build ==

Tahoe will download and install most of the libraries it requires when you
run "{{{make}}}". You might want to pre-download these libraries: perhaps you
are about to get on an airplane, or you anticipate having poor network
connectivity, or you just don't like the idea of a so-called compile step
using the network (the download step uses !PyPI to figure out where to
download these libraries from, so you might be concerned that it or one of
the project web pages it references has been modified to point at something
malicious).

This disconnected-build operation is supported in two ways. When building
from a darcs checkout, you can download the latest "tahoe-deps" bundle from
http://allmydata.org/source/tahoe/deps/tahoe-deps.tar.gz . Unpack this in
your source tree, and the build process will grab any necessary libraries
from its {{{tahoe-deps/}}} directory instead of downloading them from the
internet. You can also unpack tahoe-deps into the parent directory to share
it between multiple trees.

Alternatively, if you are building from a tarball (either a release tarball
from http://allmydata.org/source/tahoe/releases/ , or a continually-generated
current-trunk tarball from http://allmydata.org/source/tahoe/tarballs/ ), you
can simply download the -SUMO version of the tarball instead of the regular
one. The "SUMO" tarball includes the current tahoe-deps bundle pre-unpacked
in the source tree.

The tahoe-deps bundle is updated every once in a while, as new versions of
the dependent libraries are released, or as Tahoe becomes dependent upon new
things. The http://allmydata.org/source/tahoe/deps/ directory contains
historical ones, but there should never be a reason to use anything but the
latest. The tahoe-deps bundle contains a README that has a version number.


== Installing Outside The Source Tree ==

If you want to use Tahoe without keeping the source tree around, you will
need to actually install it somewhere. You have several options.

=== Installing The Latest Release ===

"{{{easy_install allmydata-tahoe}}}", run from any system that has
easy_install and setuptools installed, will download the latest release of
Tahoe (and its dependencies, all found via PyPI), build everything, and
install it into the standard place for python libraries on your system. On
unix platforms this usually goes into {{{/usr/lib/python2.5/site-packages/}}}
and {{{/usr/bin/tahoe}}} .

On Debian or Ubuntu linux systems, you can install pre-compiled packages by
adding the allmydata.org APT repository to your {{{/etc/apt/sources.list}}}
and installing the "allmydata-tahoe" package. See DownloadDebianPackages for
details.

Windows users can use an installer, which also provides the
[http://allmydata.com AllMyData] backup client, and a SMB/winfuse -based
frontend. These installers can be downloaded from (TODO: they're built, but
where are they downloadable?).

Mac users can use a .dmg file (also an installer?), which provides a simple
GUI app to launch the tahoe node. These can be downloaded from (TODO: same
problem).

=== Installing From A Source Tree ===

These commands will take the current source tree and install its contents
somewhere else on your system. This is the traditional meaning of "install".

The "{{{setup.py install}}}" target will install Tahoe (but not its
dependencies) into the standard place for python libraries on your system: on
Unix platforms this usually goes into {{{/usr/lib/python2.5/site-packages/}}}
and {{{/usr/bin/tahoe}}} .

The "{{{make install}}}" target is a wrapper around "{{{setup.py install}}}"
that uses {{{--single-version-externally-managed}}} to bypass the extra
checking that setuptools does. This allows "{{{make install}}}"  to work the same way as traditional unix
software (via GNU autoconf, etc).

("{{{make install PREFIX=/usr/local}}}" does not currently work -- see #703.)

TODO: There should be some way to use "{{{setup.py easy_install}}}" to install
Tahoe '''and''' its dependencies into the system somewhere, but I haven't
been able to figure out how.

=== Creating a binary distribution From A Source Tree ===

These commands will take the current source tree and create a single-file
installer (or some other form of binary distribution). The
installer-like-thing can then be moved to some other system and installed
there.

The "{{{setup.py bdist_egg}}}" command will create a single-file .egg in the
{{{dist/}}} directory, which can be manually copied onto your PYTHONPATH
somewhere. The .egg will declare its dependencies, but will not include them:
you must arrange for them to be installed before the .egg will be usable.

The "{{{make deb-PLATFORM-head}}}" target (i.e. {{{make deb-hardy-head}}})
will create a debian package with the current tree's Tahoe code. This .deb
file will be placed in the parent directory. The debian package will declare
dependencies on the other libraries that it needs (like foolscap and zfec),
but it will not include any code from them. The allmydata.org APT repository
(see DownloadDebianPackages for details) has packages for the dependencies
that aren't already in Debian proper.

The "{{{make windows-exe}}}" and "{{{make windows-installer}}}" commands will
create a windows executable, and the corresponding installer.

The "{{{make mac-exe}}}" and "{{{make mac-dist}}}" commands will create a
Macintosh OS-X executable and the corresponding installer (.dmg) file.

== Platform-specific Notes ==

=== Debian/Ubuntu ===

Tahoe is primarily developed on Debian/Ubuntu machines. You can either build
from source (as described by this page), or download pre-compiled debian
packages for several distributions. See the DownloadDebianPackages page for
details.

=== Windows ===

The following procedure will install and run Tahoe on Windows.  Note that this assumes that you install Python in the default location (C:\Python26), if you choose another location you'll need to adjust the instructions below:

1. Download and install Python 2.6.2 from http://www.python.org/ftp/python/2.6.2/python-2.6.2.msi.

2. Download and install pywin32 from http://sourceforge.net/projects/pywin32/files/pywin32/Build%20214/pywin32-214.win32-py2.6.exe/download.

3. Download the latest Tahoe snapshot from http://allmydata.org/source/tahoe/snapshots/. Unpack it in a convenient place, such as C:\tahoe.

4. Open a command prompt and cd to the top of the Tahoe tree (e.g. cd \tahoe).

5. Run "C:\Python26\python setup.py build". Wait a bit until it stops working. Note that you need a working network connection because it will download various dependencies.

6. Run "C:\Python26\python setup.py install". Wait a bit until it stops working. Again, you may need a working network connection.

7. Run "C:\Python26\Scripts\tahoe create-client --basedir C:\tahoebase".  Choose an appropriate base directory.

8. Run "notepad C:\tahoebase\tahoe.cfg" to edit your config file. Paste in the FURL of the introducer for the grid you want to connect to.  The test grid FURL is pb://todjw7qkb4dgq4fkeo7cqydcu5vneioh@tahoecs2.allmydata.com:52106/introducer.

9. Run "C:\Python26\Scripts\tahoe start --basedir C:\taboebase". Your node will start running and connect to the grid. The Windows firewall may ask whether or not to allow python to make network connections. Say yes.

=== What if that doesn't work? ===

If the build or install steps result in an error that says a compiler is needed, install the MinGW C/C++ compiler as follows:

1. Download and install MinGW from  http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/MinGW%205.1.4/MinGW-5.1.4.exe/download. The installer will prompt you for what components to install. You need the base components plus g++.

2. Configure distutils to use MinGW. To configure distutils to use mingw32, create a file called "distutils.cfg" in C:\Python26\lib\distutils, and put in that file:

{{{
[build]
compiler=mingw32
}}}

3. Add the MinGW binary path to your Path variable. To do that, go to the control panel (classic view), double-click "System", click on the "Advanced" tab, click on the "Environment Variables" button, scroll down to the "Path" variable in the "System Variables" list, double-click it, and append ";C:\MinGW\bin" to the path.  If you installed MinGW in some place other than C:\MinGW, adjust the path appropriately.

After installing the compilers, repeat the "build" and "install" steps.

If you prefer to use Python 2.5, you must install a 2.5 build of pywin32 and also install OpenSSL or Tahoe will fail to run with an error about being unable to find ssl.dll.  To install OpenSSL:

1. Download and install the Visual Studio 2008 redistributables from  http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF&displaylang=en. This is needed for OpenSSL.

2. Download and install OpenSSL v.9.8k Light from  http://www.slproweb.com/products/Win32OpenSSL.html.

=== How do I make it run as a Windows service? ===

http://agiletesting.blogspot.com/2005/09/running-python-script-as-windows.html