Changes between Initial Version and Version 1 of InstallDetails

Timestamp:

2008-09-17T22:36:16Z (17 years ago)

Author:

warner

Comment:

add more build/install information

InstallDetails

@@ +1 @@
+= 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 .
+
+== 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.
+
+== 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}}}" 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 (note that the authoritative list of packages is in the
+"{{{Build-Depends:}}}" clause of
+[source:misc/sid/debian/control 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
+supporting libraries installed. The authoritative list of packages is in the
+{{{Depends:}}} clause of
+[source:misc/sid/debian/control misc/sid/debian/control], and includes:
+
+ * 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.
+