From c0d1f05feb674a45fa8ec6c3d4af3275c6b42c20 Mon Sep 17 00:00:00 2001
From: warner <>
Date: Wed, 17 Sep 2008 22:36:16 +0000
Subject: [PATCH] add more build/install information

[Imported from Trac: page InstallDetails, version 1]
---
 InstallDetails.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 InstallDetails.md

diff --git a/InstallDetails.md b/InstallDetails.md
new file mode 100644
index 0000000..1bf98f4
--- /dev/null
+++ b/InstallDetails.md
@@ -0,0 +1,157 @@
+# Additional Build/Install Documentation
+
+Hopefully, the basic install docs in
+[docs/install.html](http://allmydata.org/source/tahoe/trunk/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](DownloadDebianPackages) for
+details.
+
+Windows users can use an installer, which also provides the
+[AllMyData](http://allmydata.com) 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.
+