README for TreePackager
=======================


TreePackager is a tool to automatically build debian packages.


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
  git-core
  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 most of the hints to get you
started.  Some more information is in the "Configuring a packager"
section below.


Configuring a packager
~~~~~~~~~~~~~~~~~~~~~~

The configuration file contains one section for each packager.  The
section name starts with a "pkg_" prefix.  The possible options are
described in demo.cfg.  However there are some things that need to be
set up outside of the config file.

Each packager has a base directory (the base_dir option in the
corresponding pkg_-section).  One thing needed by a packager is the
contents of the debian sub-directory of the debian source package.  When
creating the source package, the packager simply copies the
sub-directory "debian" of the base_dir into the directory making up the
source tree.  How the debian directory is created and maintained is up
to you.  Usually it's a good idea to start with the debian sub-directory
an existing debian package for the software.

Once you have configured the packagers, you can create their directories
with

    bin/inittreepkg.py

This will create base directories of each packager and report some
missing steps that will have to be done manually, like creating a debian
subdirectory with the debian packaging information.


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

It's best to give the tree packager its own pbuilder configuration and
directories.  The default configuration uses a "pbuilder" sub-directory
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:

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

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


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

The web front-end consists of a single HTML-page with an overview of the
packager status and links to build logs when available.  There are two
ways to publish this front-end: as little web-server with a dynamic
web-page or as a directory with a bunch of files making up a static
web-site.

Web-server:

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

  bin/starttreepkgweb.py

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


Static pages:

The static pages are published using two programs, createstaticweb.py
and publishstaticweb.py.  createstaticweb.py is run on the system where
the tree packager runs.  publishstaticweb.py is usually run on another
system and connects via ssh and rsync to the tree packager host, creates
the files with createstaticweb.py and copies the files from the tree
packager host to a third host.

The configuration file for publishstaticweb.py is demostaticweb.cfg.
Copy this file to staticweb.cfg and adapt it to your system.  The
comments in the file describe the options.  Afterwards, run the script
with

  bin/publishstaticweb.py


Notification Mails
~~~~~~~~~~~~~~~~~~

The tree packager can send notification mails when a built fails.  This
works in a two-step process like the creation of the static web-pages.
The sample configuration file for the notification mails is
demonotification.cfg.  Copy it to notification.cfg and adapt it to your
needs.  The comments in the file describe the options.  In particular
you will want to customize the template for the notification mail to
include suitable email addresses.  To actually send notifications, run

   bin/sendnotificationmails.py

Note that this only tries to send mails when a build has failed.


Running the Tree Packager
-------------------------

After configuration, run the tree packager with

  bin/runtreepkg.py  [options] [packager...]

For each packager listed on the command line -- or all configured
packagers if none are given -- the tree packager checks out or updates
the sources and builds binary packages if the new revision hasn't been
packaged yet.

If the option --once has been given, the tree packager exits after it
has checked each packager once.  Without it, the check is done
repeatedly.  The interval between two checks can be set in the configuration
file.

Call runtreepkg.py with the --help option to see a list of the available
options.