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, do:
    -$ debian/bin/genorig.py /path/to/xen/repo

Based on the version number in the newest debian/changelog entry, a release tag
or specific commit will be used to generate the orig tar file. For now, see
commit 55129e390c in this repository, "debian/lib/python: Recognize pre / rc
versions" about more information.

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 ~/src/git/xen
    Generate tarball ../orig/xen_4.10.0.orig.tar.xz

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.
