welcome: please sign in

Revision 56 as of 2012-06-04 04:03:17

Clear message
Edit

DebianPackaging

This page describes how to make custom Debian packages for HCoop.

1. Overview

The idea is to keep track of each custom HCoop Debian package using three branches, which are as follows.

  1. upstream: The source code from the current release of the upstream software.

  2. debian: The source code plus the latest Debian packaging that Debian has for the software.

  3. master: The source code plus the latest Debian packaging plus any changes that HCoop has made to the source or the packaging.

If you are creating a native package (e.g. for configuration files) then you only have a master branch.

2. Developing Packages

Common to all of the types of packages we might develop.

2.1. Building a package

Years ago HCoop standardized on Git for VersionControl; as such we're using git-buildpackage to maintain our packages.

First, make sure you are on the "master" branch by running:

git branch -l

If you see an asterisk by "master", you're on the right branch.

If we want to build the package with some uncommitted changes, as a sanity check, then do:

git-buildpackage --git-ignore-new

When it comes time to test the changes, build the package using:

git-buildpackage

The packages will be built and placed in the parent directory. To indicate that we are done making changes to this particular version of the Debian package, tag it with:

git-buildpackage --git-tag

This makes the package version show up when you do git tag -l, for easy diffing and viewing.

2.2. New Packages

After creating the git-buildpackage repository, push it to the public HCoop debian packages git area:

gbp-create-remote-repo --remote-url-pattern=/afs/hcoop.net/user/h/hc/hcoop/.hcoop-git/debian/'%(pkg)s'.git

We may revisit only having one are for Debian packages at a later time.

3. Creating a Configuration Package

Background:

By storing configuration in Debian repositories and taking advantage of the debathena tools, we are able to preseed installations, and better distribute configuration that needs to be coherent across all machines.

Quirks:

Our configuration build trees are kept in /afs/hcoop.net/common/debian/src/hcoop/. To create a new repository:

cd /afs/hcoop.net/common/debian/src/hcoop/
mkdir -p hcoop-$package-config/hcoop-$package-config
cd hcoop-$package-config/hcoop-$package-config
git init
dh_make --native --indep
# clean up *.ex files, update control, rules, etc. using http://debathena.mit.edu/config-packages/ or current packages as a guide
# make sure it builds
dh_clean
git add debian/** #and any other files
git commit
git-buildpackage --git-tag

4. Forking a Debian Package

Once upon a time http://backports.debian.org was not part of Debian and we had to maintain our own backports. This might be needed in the future if we want to pull software that isn't backported officially, but consider the following officially discouraged.

4.1. Making a new custom package

If you want to make changes to an existing Debian package, and we haven't made our own custom package before, then do the following.

mkdir -p /afs/hcoop.net/common/debian/src/backports/<pkg>/<upstream-version>
cd /afs/hcoop.net/common/debian/src/backports/<pkg>/<upstream-version>
# Browse http://packages.debian.org/<pkg> and find a link to a dsc file
# If you already have the .dsc, .diff.gz, and orig tarball downloaded
# to the current directory, then skip this step.
dget http://path/to/file.dsc
git-import-dsc --debian-branch=debian <pkg>-<ver>.dsc
cd <pkg>

These last two steps create a subdirectory named after the package. The subdirectory has the complete source, including the ./debian directory. The original tarball (without ./debian) is in the "upstream" branch, and the original stuff plus Debian changes would be in the "debian" branch, and a copy of the contents of the "debian" branch is placed in the "master" branch. You will be in the "master" branch now.

Make your HCoop-specific changes (preferably in an incremental and atomic fashion) and commit them using git.

4.1.1. hcoopifying the debian package

  1. Open debian/changelog in emacs and invoke M-x debian-changelog-mode.

  2. Press C-c C-v to create a new entry in the changelog and set the version so that the portion after the dash is hcoop1 (or hcoop2, etc).

  3. Change the distribution to $stable-backports (as of 2012, this is squeeze-backports)

  4. Add a comment
  5. Press C-c C-c to close the entry.

  6. Save and exit.

4.2. New package from Debian

When a new Debian package comes out, and we want to incorporate their changes, the routine will be as follows.

cd ..
dget -x <URL to dsc file on packages.debian.org>
cd <pkgname>
git checkout debian
cd ../<pkgname>-<ver>
GIT_DIR=../<pkgname>/.git git add .
GIT_DIR=../<pkgname>/.git git add -u .
GIT_DIR=../<pkgname>/.git git commit -m "Import Debian package <ver>-<patch>"
cd ../<pkgname>
rm -fr ../<pkgname>-<ver>
git clean -d && git reset --hard
git tag -a -m "Debian release <ver>-<patch>" debian/<ver>-<patch>

OK, let's stop to take a breather. Here's what the effect of all of this stuff has been.

Now we'll want to switch back to the master branch (where we keep HCoop-specific changes) and merge the latest Debian changes.

git checkout master
git merge debian
[fix any conflicts, particularly in debian/changelog]
git commit

Now, make a new debian/changelog entry and list the changes that were kept in our version. When done, commit, build packages, and tag the version of the package as in the Building a Package section.

4.3. New upstream version not yet in Debian

If you want to update an existing custom HCoop Debian package with a new version of the upstream program, and no Debian package yet exists for that version, then you'll need to work with the upstream tarball for the new release directly. Instructions are as follows.

When Debian catches up to our blazing pace and makes their own package, perhaps with changes that we want, then we will need to use some trickery to make the packages sync up.

5. Debian Archive

5.1. Installing Packages to the Archive

debarchiver is configured to scan /afs/hcoop.net/common/debian/archive/incoming/ every five minutes. The easiest way to install a package to the archive is to use dput on the .changes file.

Example ~/.dput.cf:

[hcoop]
fqdn = local
method = local
incoming = /afs/hcoop.net/common/debian/archive/incoming/
allow_unsigned_uploads = 1

5.2. sources.list

Preseeding should take care of setting up the repository, but:

/etc/apt/sources.list should contain:

deb http://debian.hcoop.net/ squeeze main hcoop-config
deb-src http://debian.hcoop.net/ squeeze main hcoop-config