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= 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.