docs/debian.rst

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