Xen packaging for Debian
========================

Step 1: Get the upstream source
-------------------------------

The upstream Xen source code is not included with the packaging code
repository.

When doing additional work on a new debian revision of an existing package for
a specific upstream version, grab the orig tar that's already in the package
archives and put it just outside the directory of this repository.

To package a new upstream version, an orig tar can be generated by pointing the
genorig.py progam to your local xen git repository.

Clone the upstream git repository somewhere (not inside the packaging
directory, somewhere else!):

    -$ git clone https://xenbits.xen.org/git-http/xen.git

After cloning it, we should generate an orig tar from the upstream source.

Based on the version number in the newest debian/changelog entry, a release tag
or specific commit can be used to generate the orig tar file. For example, if
the latest entry in changelog is 4.10.0-1, then this will build the orig tar
from the RELEASE-4.10.0 tag in upstream git:

    -$ debian/bin/genorig.py /path/to/xen.git
    Generate tarball ../orig/xen_4.10.0.orig.tar.xz

| **Recognized patterns**  | example | uses treeish |
|--------|------|------|
| Regular release | 4.10.2 | RELEASE-4.10.2 |
| Pre version in between stable releases with explicit commit | 4.10.2~pre+1.25e0657e00-1 | 25e0657e00 |
| Explicit commit while in rc | 4.11.0~rc6+1.35fcb982ea-1~exp1 | 35fcb982ea |
| Release candidate | 4.11.0~rc7-1~exp1 | 4.11.0-rc7 |

When a version contains an explicit commit hash, it has to be 10 characters long. Since commit ids do not sort, the +1 serves that purpose, and is incremented to +2 etc when switching to another commit.

Step 2: Combine the upstream source and packaging
-------------------------------------------------

The orig target in debian/rules is our friendly helper here:

    -$ debian/rules orig
    mkdir -p ../orig
    tar -C ../orig -xaf ../xen_4.10.0.orig.tar.xz
    rsync --delete --exclude /debian --exclude .git -a ../orig/xen-4.10.0/ .
    QUILT_PATCHES='[...]/debian/patches' QUILT_PC=.pc quilt push --quiltrc - -a -q --fuzz=0
    Applying patch version.diff
    Applying patch config-prefix.diff
    [...]
    Applying patch tools-xentoolcore-abiname.patch
    Now at patch tools-xentoolcore-abiname.patch

Step 3: Generate missing packaging files
----------------------------------------

Quite some files in the packaging are generated. At least all the files which
have version-dependent names etc.

To generate them:

    -$ debian/rules debian/control
    /usr/bin/make -f debian/rules debian/control-real
    make[1]: Entering directory '[...]'
    debian/bin/gencontrol.py
    md5sum debian/changelog [...] > debian/control.md5sum

    This target is made to fail intentionally, to make sure
    that it is NEVER run during the automated build. Please
    ignore the following error, the debian/control file has
    been generated SUCCESSFULLY.

    exit 1
    debian/rules:79: recipe for target 'debian/control-real' failed
    make[1]: *** [debian/control-real] Error 1
    make[1]: Leaving directory '[...]'
    debian/rules:69: recipe for target 'debian/control' failed
    make: *** [debian/control] Error 2

This looks a bit wonky, but it makes sure we're not able to do the actual
package build without having taken this step.

Step 4: Build the package
-------------------------

Use your favourite way to build the package. Mine is pbuilder, so I'm doing
something like

    -$ pdebuild --use-pdebuild-internal \
      --auto-debsign --debsign-k ABCDEF \
      --configfile /home/knorrie/.pbuilderrc-sid

Step 5: Cleanup and reset everything
------------------------------------

To cleanup the whole packaging environment, just do a git clean -dfx, and
you're ready to continue back at step 2.
