Additional Build/Install? Documentation

Hopefully, the basic install docs in ​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 .

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 ​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" and "make install PREFIX=/usr/local" to work the same way as traditional unix software (via GNU autoconf, etc).

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?

The Tahoe build process will download and install many of its dependencies when you run make or setup.py build_tahoe. The base set of functionality that it cannot build on its own are provided by the following debian packages, so you must have these installed before you will be able to do much of anything. (note that the authoritative list of packages is in the "Build-Depends:" clause of misc/sid/debian/control):

• build-essential (this includes gcc, g++, make, and the headers in libc-dev)
• debhelper
• cdbs
• python-central
• python-setuptools
• python
• python-dev

In addition, to use the "make deb-PLATFORM-head" target, you will also need the "debchange" utility from the "devscripts" package, and the "fakeroot" package.

To actually run a Tahoe node from a debian package, you will need the following supporting libraries installed. (again, the authoritative list of packages is in the Depends: clause of misc/sid/debian/control)

• python-twisted-core
• python-twisted-names
• python-foolscap
• python-pyopenssl
• python-nevow
• python-simplejson
• python-zfec
• python-pycryptopp

Even if you don't intend to create a Tahoe .deb package, you can install the supporting libraries from debian packages to reduce the build-time download-and-compile work.

Please read DownloadDebianPackages if you just want to install pre-compiled debian packages of the latest "trunk" source code.