README for TreePackager
=======================
2007-03-19, Bernhard Herzog <bh@intevation.de>


TreePackager is a tool to automatically build debian packages from SVN.


Prerequisites
-------------

You need the following software to run TreePackager.  In the list below,
parentheses contain the name of the corresponding package in Debian Etch
if its not the same as the software.  The version required is usually
the one from debian etch.

  Python 2.4   (python2.4-minimal)
  Debian devscripts (devscripts)
  subversion
  pbuilder
  sudo
  bzip2

For the web front-end you also need the following software:

  Genshi (python-genshi)
  CherryPy (python-cherrypy)

Some of the packagers require additional software.  The KDEPIM
enterprise branch packagers require the following additional software:

  autoconf2.13
  automake1.9


Installation
------------

You can run the tree packager itself directly from the source tree.
However, you need to configure it first and setup pbuilder.


Configuration
-------------

To understand the configuration, first a few notes about the
architecture of TreePackager.  The TreePackager consist of one program
that periodically updates svn working directories and if something has
changed, builds a new debian package from the working directory.  The
program should run as a normal user.  The sample configuration assumes
that it's the user "builder" with a home directory "/home/builder".  The
default configuration manages a directory tree under
"/home/builder/enterprise".

The binary packages are built with pbuilder.  Because pbuilder uses a
chroot environment to build the packages, it must be run as root.  The
tree packager therefore needs a way to run pbuilder as root even though
itself runs as a non-root user.  By default the tree packager uses sudo,
so you have to setup sudo to allow the tree packager user to invoke
pbuilder without a password.  This can be accomplished with the
following line in /etc/sudoers (using the default user name):

   builder ALL = NOPASSWD: /usr/sbin/pbuilder


Configure TreePackager
~~~~~~~~~~~~~~~~~~~~~~

The file demo.cfg contains example configuration that contains most of
what is needed to package KDEPIM and kde-i18n from the KDEPIM enterprise
branch.  Copy this file to treepkg.cfg and adapt it to your needs.  The
comments in the file should provide enough hints to get you started.


Configure pbuilder
~~~~~~~~~~~~~~~~~~

It's best to give the tree packager its own pbuilder configuration and
directories.  The default configuration uses a "pbuilder" subdirectory
in /home/builder/enterprise.  If you have created the treepkg.cfg file
with at least one packager and the correct root_cmd and pbuilderrc
options (the defaults for both should be OK if you use sudo as described
above), you can create the directories, the pbuilder configuration and
the chroot environment with the script initpbuilder.py like this:

   ./initpbuilder.py --mirrorsite=<URL of preferred debian mirror>

You can specify some more mirrors with the --othermirror option.  For
more information run "./initpbuilder.py --help" and consult the pbuilder
documentation.


Configure the web front-end
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default configuration should be OK in most cases.  If you want you
can customize it in cherrypy.cfg.  Start the web front-end with

  ./starttreepkgweb.py

starttreepkgweb has some options to specify which configuration files to use.