Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• Sugar/README

The following documentation has been written for core sugar package but applies for most sugar packages

Building core sugar package for Debian

The source package for core sugar need no special handling for normal package builds.

Developing core sugar package for Debian

The source of core sugar package is developed using git and the helper tool git-buildpackage, with all official releases tagged and signed and binary diffs of tarballs stored using pristine-tar. This is documented below /usr/share/doc/git-buildpackage/manual-html/ .

Upstream development is tracked by fetching upstream Git and importing release tags into the "upstream" branch before git-buildpackage imports.

A custom build target shows current upstream and packaging versions:

    debian/rules print-version

Current upstream tarball can be prepared using this other build target:

    debian/rules get-orig-source

To switch to newer upstream source, first add a dummy changelog entry and comment out DEB_UPSTREAM_TARBALL_MD5 before getting the source:

    dch -v ${new_upstream_version}-1 "Dummy changelog entry"
    sed -i -e 's/^\(DEB_UPSTREAM_TARBALL_MD5\b\)/#\1/' debian/rules
    debian/rules get-orig-source

Store new md5sum to help ensure identical source is received later.

Before injecting a newer upstream tarball, use below commands to sync with upstream Git, to adopt upstream commit messages while minimizing size of our Git.

    git remote add upstream-repo git://upstream.example.com/project.git
    git fetch --tags upstream-repo
    git checkout upstream
    git merge upstream-release-tag
    git checkout master

Note:

• Use first line above only initially - skip it on later updates.

• In case 'git merge upstream-release-tag' fails to merge the upstream contents, "reset" the "upstream" branch to use upstream content:

      git checkout -b reset-upstream-to-vVERSION_NUMBER vVERSION_NUMBER
      git merge --strategy ours upstream
      git checkout upstream
      git merge reset-upstream-to-vVERSION_NUMBER
      git branch -d reset-upstream-to-vVERSION_NUMBER
  
      *use vVERSION_NUMBER like v0.89

  Above commands first create a branch from the vVERSION_NUMBER tag, pseudo-merges HEAD of upstream branch into that, and then merges back the result on top of the "upstream" branch and cleans up the temporary branch. For more information, read the section on MERGE STRATEGIES in "git merge --help".

If upstream do not provide tags corresponding to tarball releases then use something like the following instead:

    git remote add upstream-repo git://upstream.example.com/project.git
    git fetch upstream-repo
    git log --pretty="format:%h %s" upstream-repo/master..upstream
    git checkout upstream
    git pull . newest-refspec-older-than-release-from-above-git-log
    git checkout master

To do a package release from upstream Git snapshot, first look at upstream development for a good place to release, and tag by its date, replacing "~" with "." to mimic git-buildpackage logic (replace timestamp and commit hash below with real ones based on chosen commit).

    git log --abbrev-commit upstream-repo/master
    git tag -s -m "Upstream snapshot" upstream/0.2.git20080130 61279f8
    dch -r -v "0.2~git20080130-1" "New upstream Git snapshot."

Setting DEB_MAINTAINER_MODE=1 enables additional build routines helpful during development of the package, but unfit for normal builds. This typically includes the CDBS feature of auto-updating debian/control with CDBS-related build-dependencies, which is forbidden by Debian Policy as build environment must not change during automated builds.

Maintaining packaging build routines

The core sugar source package wraps debhelper commands and other tedious parts of the build routines using the CDBS framework. Please refer to the actual makefile snippets included from debian/rules for details on their purpose and ways to override defaults - or read the CDBS manual at in/usr/share/doc/cdbs/cdbs-doc.pdf.gz .