Note: This web site is only kept up to date for OSG Software 1.2 (VDT 2.0.0). If you are looking for information for the most recent release, the RPM-based OSG Software 3.0, please see the OSG documentation web site

Process for Updating a Debian Package

This document contains the basic process for updating a LIGO Debian package, from start all the way through to putting the revised package into the development repository. Along the way, it documents many of the standand Debian and locally developed tools for doing Debian packaging work.

Except for locally developed scripts, the ultimate references for Debian packaging are the Debian New Maintainers’ Guide and the Debian Policy Manual.

Most of the locally developed helper scripts below are stored in Subversion at SVNROOT/ligo/trunk/common/debian. Check out this directory and put it in your PATH. They are not well documented, but all are short and simple enough to figure out if need be. In most cases, running the script with no arguments will produce enough help information to run the script.

In the instructions below, PackageID is one of the following:

• package_version — for a native Debian package
• package_version-revision — for a package of upstream source

1. Make sure working files are up-to-date and/or saved:

   sync-files /path/to/sync.data

   This workflow assumes that you have a Subversion checkout of the LIGO trunk, and then separate working directories for each (source) package. The sync-files script synchronizes files between a Subversion checkout and a working directory; the given sync.data path, expected to be contained within the Subversion checkout for the package, in the debian subdirectory, contains all the data needed to synchronize the two areas. This step, here at the start of the process, is just to make sure all prior changes were synchronized before making new changes to the working directory.

2. Check Subversion to make sure files are up-to-date:

   svn status --show-updates /path/to/subversion/checkout

   Again, just to make sure that all prior changes were committed.

3. If this package is Debian-only (no upstream source) or if it contains a new release of upstream software, make a new working directory for the release:

   Debian package

   1. Create new source directory named package-version
   2. Update the package’s sync.data to reference the new working directory
   3. Run sync-files on the package to populate the new working directory

   Upstream package

   1. Download the new source tarball to the parent of the package’s current working directory
   2. Expand the tarball and make sure the resultant directory is named package-version
   3. Rename the tarball or recreate it (if the expanded directory named changed) to package-version.orig.tar.gz
   4. Update the package’s sync.data to reference the new working directory
   5. Run sync-files on the package to populate the new working directory
4. Change to the new working directory
5. Create new revision (upstream software) or version (Debian software)

   dch -i message

   This command, a standard Debian tool, creates a new entry in the debian/changelog file. This is a critical step, because the changelog is the only source of the package revision number. Use the dch command, because it gets all the formatting right. But, check over the fields of the new changelog entry to make sure they match the older changelog entries and your personal info.

6. Check and/or update the metadata files in the debian directory:
   • changelog
   • control
   • copyright
   • rules
   • Others as needed — see the Debian New Maintainers’ Guide for more information
7. Install build dependencies:

   verify-build-dependencies /path/to/working/directory

   If this script detects missing build dependencies, it will print a message describing how to get them. You may want to note the installed packages now, so that you can remove them later and leave the build machine in a clean state.

8. Do a test build:

   debian/rules build
   fakeroot debian/rules binary

   If any step fails or produces bad output, go back and fix things until it is good.

   Once the build and packaging is working correctly, clean up:

   fakeroot debian/rules clean

9. Check all build steps and their clean targets:

   check-build-and-clean /path/to/working/directory ... build binary ...

   This locally made script exercises the build and clean targets of your rules file. For each target, it snapshots the working directory, executes the target, cleans the target (with clean-target), then diffs the working directory against the original snapshot. Fix any problems that are detected.

10. Make sure files are synced:

    sync-files /path/to/sync.data

    This step is critical, because the next step will remove the debian directory and reconstruct it from the Subversion directory. Thus, unsynchronized changes will be lost unless you do this step now!

11. When everything is ready, prepare for the final (pbuilder) builds:

    prepare-for-build

    This is a script that I have written for most of my working directories on vdt-debian-test. It would be great to write a general-purpose version and put it in Subversion, but I have not done so yet. Essentially, it makes sure the working directory is ready for a clean build and packaging by removing and repopulating it from authoritative sources.

12. Update pbuilder installs:

    sudo /home/cat/pbuilder/update-amd64
    sudo /home/cat/pbuilder/update-i386

    The Debian pbuilder tool does clean builds in a chroot environment. First, you must make sure that the pre-made pbuilder “images” are up-to-date. These commands take care of all the details.

13. Run final builds:

    sudo final-build amd64 PackageID.dsc
    sudo final-build i386 PackageID.dsc

    This simple wrapper script just makes sure that the right pbuilder commands are used to build the package. Among other things, it tells pbuilder to use a RAM disk for its working files, to speed the build process considerably.

14. Log into AFS:

    klog.afs

15. Upload build artifacts to the Debian LIGO development repository:

    upload-build PackageID

16. Re-index the repository:

    index-ligo-apt-repo development

    You must have the passphrase for the Debian signing key in order to complete this step.

17. Commit changed files to Subversion.