docs/debian.txt

   1 = Debian Support =
   2
   3 1.  Overview
   4 2.  TL;DR supporting package building instructions
   5 3.  TL;DR package building instructions for Tahoe
   6 4.  Building Debian Packages
   7 5.  Using Pre-Built Debian Packages
   8 6.  Building From Source on Debian Systems
   9
  10 = Overview ==
  11
  12 One convenient way to install Tahoe-LAFS is with debian packages.
  13 This document attempts to explain how to complete a desert island build for
  14 people in a hurry. It also attempts to explain more about our Debian packaging
  15 for those willing to read beyond the simple pragmatic packaging exercises.
  16
  17 == TL;DR supporting package building instructions ==
  18
  19 There are only four supporting packages that are currently not available from
  20 the debian apt repositories in Debian Lenny:
  21
  22     python-foolscap python-zfec argparse zbase32
  23
  24 First, we'll install some common packages for development:
  25
  26     sudo apt-get install -y build-essential debhelper cdbs python-central \
  27                     python-setuptools python python-dev python-twisted-core \
  28                     fakeroot darcs python-twisted python-nevow \
  29                     python-simplejson  python-pycryptopp devscripts \
  30                     apt-file
  31     sudo apt-file update
  32
  33
  34 To create packages for Lenny, we'll also install stdeb:
  35
  36     sudo apt-get install python-all-dev
  37     STDEB_VERSION="0.5.1"
  38     wget http://pypi.python.org/packages/source/s/stdeb/stdeb-$STDEB_VERSION.tar.gz
  39     tar xzf stdeb-$STDEB_VERSION.tar.gz
  40     cd stdeb-$STDEB_VERSION
  41     python setup.py --command-packages=stdeb.command bdist_deb
  42     sudo dpkg -i deb_dist/python-stdeb_$STDEB_VERSION-1_all.deb
  43
  44 Now we're ready to build and install the zfec Debian package:
  45
  46     darcs get http://allmydata.org/source/zfec/trunk zfac
  47     cd zfac/zfec/
  48     python setup.py sdist_dsc
  49     cd `find deb_dist -mindepth 1 -maxdepth 1 -type d` && \
  50     dpkg-buildpackage -rfakeroot -uc -us
  51     sudo dpkg -i ../python-zfec_1.4.6-r333-1_amd64.deb
  52
  53 We need to build a pyutil package:
  54
  55     wget http://pypi.python.org/packages/source/p/pyutil/pyutil-1.6.1.tar.gz
  56     tar -xvzf pyutil-1.6.1.tar.gz
  57     cd pyutil-1.6.1/
  58     python setup.py --command-packages=stdeb.command sdist_dsc
  59     cd deb_dist/pyutil-1.6.1/
  60     dpkg-buildpackage -rfakeroot -uc -us
  61     sudo dpkg -i ../python-pyutil_1.6.1-1_all.deb
  62
  63 We also need to install argparse and zbase32:
  64
  65     sudo easy_install argparse # argparse won't install with stdeb (!) :-(
  66     sudo easy_install zbase32 # XXX TODO: package with stdeb
  67
  68 Finally, we'll fetch, unpack, build and install foolscap:
  69
  70     # You may not already have Brian's key:
  71     # gpg --recv-key 0x1514A7BD
  72     wget http://foolscap.lothar.com/releases/foolscap-0.5.0.tar.gz.asc
  73     wget http://foolscap.lothar.com/releases/foolscap-0.5.0.tar.gz
  74     gpg --verify foolscap-0.5.0.tar.gz.asc
  75     tar -xvzf foolscap-0.5.0.tar.gz
  76     cd foolscap-0.5.0/
  77     python setup.py --command-packages=stdeb.command sdist_dsc
  78     cd deb_dist/foolscap-0.5.0/
  79     dpkg-buildpackage -rfakeroot -uc -us
  80     sudo dpkg -i ../python-foolscap_0.5.0-1_all.deb
  81
  82 == TL;DR package building instructions for Tahoe ==
  83
  84 If you want to build your own Debian packages from the darcs tree or from
  85 a source release, do the following:
  86
  87     cd ~/
  88     mkdir src && cd src/
  89     darcs get --lazy http://allmydata.org/source/tahoe-lafs/trunk tahoe-lafs
  90     cd tahoe-lafs
  91     # set this for your Debian release name (lenny, sid, etc)
  92     make deb-lenny-head
  93     # You must have your dependency issues worked out by hand for this to work
  94     sudo dpkg -i ../allmydata-tahoe_1.6.1-r4262_all.deb
  95
  96 You should now have a functional desert island build of Tahoe with all of the
  97 supported libraries as .deb packages. You'll need to edit the Debian specific
  98 /etc/defaults/allmydata-tahoe file to get Tahoe started. Data is by default
  99 stored in /var/lib/tahoelafsd/ and Tahoe runs as the 'tahoelafsd' user.
 100
 101 == Building Debian Packages ==
 102
 103 The Tahoe source tree comes with limited support for building debian packages
 104 on a variety of Debian and Ubuntu platforms. For each supported platform,
 105 there is a "deb-PLATFORM-head" target in the Makefile that will produce a
 106 debian package from a darcs checkout, using a version number that is derived
 107 from the most recent darcs tag, plus the total number of revisions present in
 108 the tree (e.g. "1.1-r2678").
 109
 110 To create debian packages from a Tahoe tree, you will need some additional
 111 tools installed. The canonical list of these packages is in the
 112 "Build-Depends" clause of misc/sid/debian/control , and includes:
 113
 114  build-essential
 115  debhelper
 116  cdbs
 117  python-central
 118  python-setuptools
 119  python
 120  python-dev
 121  python-twisted-core
 122
 123 In addition, to use the "deb-$PLATFORM-head" target, you will also need the
 124 "debchange" utility from the "devscripts" package, and the "fakeroot" package.
 125
 126 Some recent platforms can be handled by using the targets for the previous
 127 release, for example if there is no "deb-hardy-head" target, try building
 128 "deb-gutsy-head" and see if the resulting package will work.
 129
 130 Note that we haven't tried to build source packages (.orig.tar.gz + dsc) yet,
 131 and there are no such source packages in our APT repository.
 132
 133 == Using Pre-Built Debian Packages ==
 134
 135 The allmydata.org site hosts an APT repository with debian packages that are
 136 built after each checkin. The following wiki page describes this repository:
 137
 138  http://allmydata.org/trac/tahoe/wiki/DownloadDebianPackages
 139
 140 The allmydata.org APT repository also includes debian packages of support
 141 libraries, like Foolscap, zfec, pycryptopp, and everything else you need that
 142 isn't already in debian.
 143
 144 == Building From Source on Debian Systems ==
 145
 146 Many of Tahoe's build dependencies can be satisfied by first installing
 147 certain debian packages: simplejson is one of these. Some debian/ubuntu
 148 platforms do not provide the necessary .egg-info metadata with their
 149 packages, so the Tahoe build process may not believe they are present. Some
 150 Tahoe dependencies are not present in most debian systems (such as foolscap
 151 and zfec): debs for these are made available in the APT repository described
 152 above.
 153
 154 The Tahoe build process will acquire (via setuptools) most of the libraries
 155 that it needs to run and which are not already present in the build
 156 environment).
 157
 158 We have observed occasional problems with this acquisition process. In some
 159 cases, setuptools will only be half-aware of an installed debian package,
 160 just enough to interfere with the automatic download+build of the dependency.
 161 For example, on some platforms, if Nevow-0.9.26 is installed via a debian
 162 package, setuptools will believe that it must download Nevow anyways, but it
 163 will insist upon downloading that specific 0.9.26 version. Since the current
 164 release of Nevow is 0.9.31, and 0.9.26 is no longer available for download,
 165 this will fail.
 166
 167 The Tahoe source tree currently ships with a directory full of tarballs of
 168 dependent libraries (misc/dependencies/), to enable a "desert-island build".
 169 There are plans to remove these tarballs from the source repository (but
 170 still provide a way to get Tahoe source plus dependencies). This Nevow-0.9.26
 171 -type problem can be mitigated by putting the right dependency tarball in
 172 misc/dependencies/ .