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
~~~~~~~~~~~~~~~~~~

Currently the tree packager assumes that pbuilder has already been set up
and that the default configuration is suitable for the purposes the tree
packager instance.  Normally, the default way of setting up sudo should
be OK.  There is one important interaction with sudo that you need to be
aware of, though: when the user builder starts pbuilder via sudo,
pbuilder uses ~builder/.pbuilderrc as its standard configuration file.


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.