bh@42: README for TreePackager bh@42: ======================= bh@42: bh@42: aheinecke@321: TreePackager is a tool to automatically build debian packages. bh@42: bh@42: bh@42: Prerequisites bh@42: ------------- bh@42: bh@42: You need the following software to run TreePackager. In the list below, bh@42: parentheses contain the name of the corresponding package in Debian Etch bh@42: if its not the same as the software. The version required is usually bh@42: the one from debian etch. bh@42: bh@42: Python 2.4 (python2.4-minimal) bh@42: Debian devscripts (devscripts) bh@42: subversion bh@42: pbuilder aheinecke@321: git-core bh@42: sudo bh@42: bzip2 bh@42: bh@42: For the web front-end you also need the following software: bh@42: bh@42: Genshi (python-genshi) bh@42: CherryPy (python-cherrypy) bh@42: bh@42: Some of the packagers require additional software. The KDEPIM bh@42: enterprise branch packagers require the following additional software: bh@42: bh@42: autoconf2.13 bh@42: automake1.9 bh@42: bh@42: bh@42: Installation bh@42: ------------ bh@42: bh@42: You can run the tree packager itself directly from the source tree. bh@42: However, you need to configure it first and setup pbuilder. bh@42: bh@42: bh@42: Configuration bh@42: ------------- bh@42: bh@42: To understand the configuration, first a few notes about the bh@42: architecture of TreePackager. The TreePackager consist of one program bh@42: that periodically updates svn working directories and if something has bh@42: changed, builds a new debian package from the working directory. The bh@42: program should run as a normal user. The sample configuration assumes bh@42: that it's the user "builder" with a home directory "/home/builder". The bh@42: default configuration manages a directory tree under bh@42: "/home/builder/enterprise". bh@42: bh@42: The binary packages are built with pbuilder. Because pbuilder uses a bh@42: chroot environment to build the packages, it must be run as root. The bh@42: tree packager therefore needs a way to run pbuilder as root even though bh@42: itself runs as a non-root user. By default the tree packager uses sudo, bh@42: so you have to setup sudo to allow the tree packager user to invoke bh@42: pbuilder without a password. This can be accomplished with the bh@42: following line in /etc/sudoers (using the default user name): bh@42: bh@42: builder ALL = NOPASSWD: /usr/sbin/pbuilder bh@42: bh@42: bh@42: Configure TreePackager bh@42: ~~~~~~~~~~~~~~~~~~~~~~ bh@42: bh@42: The file demo.cfg contains example configuration that contains most of bh@42: what is needed to package KDEPIM and kde-i18n from the KDEPIM enterprise bh@42: branch. Copy this file to treepkg.cfg and adapt it to your needs. The bh@71: comments in the file should provide most of the hints to get you bh@71: started. Some more information is in the "Configuring a packager" bh@71: section below. bh@71: bh@71: bh@71: Configuring a packager bh@71: ~~~~~~~~~~~~~~~~~~~~~~ bh@71: bh@73: The configuration file contains one section for each packager. The bh@71: section name starts with a "pkg_" prefix. The possible options are bh@71: described in demo.cfg. However there are some things that need to be bh@71: set up outside of the config file. bh@71: bh@71: Each packager has a base directory (the base_dir option in the bh@71: corresponding pkg_-section). One thing needed by a packager is the bh@72: contents of the debian sub-directory of the debian source package. When bh@72: creating the source package, the packager simply copies the bh@72: sub-directory "debian" of the base_dir into the directory making up the bh@72: source tree. How the debian directory is created and maintained is up bh@72: to you. Usually it's a good idea to start with the debian sub-directory bh@72: an existing debian package for the software. bh@42: bh@108: Once you have configured the packagers, you can create their directories bh@108: with bh@108: bh@108: bin/inittreepkg.py bh@108: bh@108: This will create base directories of each packager and report some bh@108: missing steps that will have to be done manually, like creating a debian bh@108: subdirectory with the debian packaging information. bh@108: bh@42: bh@42: Configure pbuilder bh@42: ~~~~~~~~~~~~~~~~~~ bh@42: bh@50: It's best to give the tree packager its own pbuilder configuration and bh@72: directories. The default configuration uses a "pbuilder" sub-directory bh@50: in /home/builder/enterprise. If you have created the treepkg.cfg file bh@50: with at least one packager and the correct root_cmd and pbuilderrc bh@50: options (the defaults for both should be OK if you use sudo as described bh@50: above), you can create the directories, the pbuilder configuration and bh@50: the chroot environment with the script initpbuilder.py like this: bh@50: thomas@78: bin/initpbuilder.py --mirrorsite=<URL of preferred debian mirror> bh@50: bh@50: You can specify some more mirrors with the --othermirror option. For thomas@78: more information run "bin/initpbuilder.py --help" and consult the pbuilder bh@50: documentation. bh@42: bh@42: bh@42: Configure the web front-end bh@42: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ bh@42: bh@70: The web front-end consists of a single HTML-page with an overview of the bh@70: packager status and links to build logs when available. There are two bh@70: ways to publish this front-end: as little web-server with a dynamic bh@70: web-page or as a directory with a bunch of files making up a static bh@70: web-site. bh@70: bh@72: Web-server: bh@70: bh@42: The default configuration should be OK in most cases. If you want you bh@42: can customize it in cherrypy.cfg. Start the web front-end with bh@42: thomas@78: bin/starttreepkgweb.py bh@42: bh@42: starttreepkgweb has some options to specify which configuration files to use. bh@70: bh@70: bh@70: Static pages: bh@70: bh@70: The static pages are published using two programs, createstaticweb.py bh@70: and publishstaticweb.py. createstaticweb.py is run on the system where bh@70: the tree packager runs. publishstaticweb.py is usually run on another bh@70: system and connects via ssh and rsync to the tree packager host, creates bh@70: the files with createstaticweb.py and copies the files from the tree bh@70: packager host to a third host. bh@70: thomas@78: The configuration file for publishstaticweb.py is demostaticweb.cfg. thomas@78: Copy this file to staticweb.cfg and adapt it to your system. The thomas@78: comments in the file describe the options. Afterwards, run the script thomas@78: with bh@70: thomas@78: bin/publishstaticweb.py bh@71: bh@71: bh@109: Notification Mails bh@109: ~~~~~~~~~~~~~~~~~~ bh@109: bh@109: The tree packager can send notification mails when a built fails. This bh@109: works in a two-step process like the creation of the static web-pages. bh@109: The sample configuration file for the notification mails is bh@109: demonotification.cfg. Copy it to notification.cfg and adapt it to your bh@109: needs. The comments in the file describe the options. In particular bh@109: you will want to customize the template for the notification mail to bh@109: include suitable email addresses. To actually send notifications, run bh@109: bh@109: bin/sendnotificationmails.py bh@109: bh@109: Note that this only tries to send mails when a build has failed. bh@109: bh@109: bh@71: Running the Tree Packager bh@71: ------------------------- bh@71: bh@71: After configuration, run the tree packager with bh@71: thomas@78: bin/runtreepkg.py [options] [packager...] bh@71: bh@71: For each packager listed on the command line -- or all configured thomas@78: packagers if none are given -- the tree packager checks out or updates bh@71: the sources and builds binary packages if the new revision hasn't been bh@71: packaged yet. bh@71: bh@71: If the option --once has been given, the tree packager exits after it bh@71: has checked each packager once. Without it, the check is done thomas@78: repeatedly. The interval between two checks can be set in the configuration bh@71: file. bh@71: bh@71: Call runtreepkg.py with the --help option to see a list of the available bh@71: options.