welcome: please sign in

Diff for "DebianPackaging"

Differences between revisions 18 and 22 (spanning 4 versions)
Revision 18 as of 2008-12-11 00:39:43
Size: 7129
Editor: ClintonEbadi
Comment: spam
Revision 22 as of 2008-12-11 13:28:32
Size: 265
Editor: ns25093
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This page describes how to make custom Debian packages for HCoop.

<<TableOfContents>>

= 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.
 1. {{{debian}}}: The source code plus the latest Debian packaging that Debian has for the software.
 1. {{{master}}}: The source code plus the latest Debian packaging plus any changes that HCoop has made to the source or the packaging.

= 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/<pkg>/<upstream-version>
cd /afs/hcoop.net/common/debian/<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.

== 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. Add a comment
 4. Press {{{C-c C-c}}} to close the entry.
 5. Save and exit.

= Building a package =

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.

= New package from Debian =

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

 * <pkgname> is the name of the package.
 * <ver> is the upstream version of the software.
 * <patch> is the patch level of the package. For example: "1". We always add an "hcoop" suffix to patch levels of packages that we modify.

{{{
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.

 * Retrieved a .dsc file from debian and expanded it into the <pkgname>-<ver> directory.
 * Switched to the debian branch.
 * Moved into the new directory.
 * Set GIT_DIR, which specifies the git metadata directory to use.
 * Added all untracked files.
 * Updated all tracked files.
 * Committed the result. Now the git metadata directory knows about this Debian package version.
 * Removed the <pkgname>-<ver> directory.
 * Reset the working directory to match the metadata, so that we get the latest changes that we just committed.
 * Tagged this particular state with the version of the package.

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.

= 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.

 * Make a directory for the new version. {{{
cd /afs/hcoop.net/common/debian/<pkgname>
mkdir <ver>
cd <ver>}}}
 * Download the new upstream tarball to this directory.
 * Rename it to {{{<pkgname>_<ver>.orig.tar.gz}}}.
 * Move the git repo for the old version over to the new directory. {{{
mv ../<old-ver>/<pkgname> .}}}
 * Run git-import-orig. {{{
cd <pkgname>
git-import-orig ../<pkgname>_<ver>.orig.tar.gz}}}
 * Resolve conflicts and built the new package.

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.

 * Change directory to {{{/afs/hcoop.net/common/debian/<pkgname>/<ver>}}}.
 * Obtain the debian .dsc file and extract the contents to <pkgname>-<ver>, as in '''New package from Debian''' section.
 * Switch to the {{{debian}}} branch. {{{
cd <pkgname>
git checkout debian}}}
 * Check in Debian's changes. {{{
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>
git add . ; git reset --hard
}}}
 * Do an "ours" merge with the {{{upstream}}} branch. This basically does a merge that is guaranteed not to have conflicts, with the end result being the contents of the current branch. This allows us to more easily merge in the changes that Debian made, later on. {{{
git merge -s ours upstream}}}
 * For instructive purposes, do a {{{git log}}}. You will see a log entry for the upstream version just below the log entry for the new Debian package. Very nifty.
 * Now switch back to the {{{master}}} branch which contains our changes and merge from the {{{debian}}} branch. {{{
git checkout master
git merge debian
}}}
 * Resolve any conflicts. You shouldn't see conflicts in the upstream source -- only the {{{debian/}}} directory might have conflicts.
 * Build and tag the package, making a new HCoop version.
<a href='http://ezpascal.strefa.pl/mythical-beasts.htm'>mythical beasts</a> <a href="http://ezpascal.strefa.pl/mythical-beasts.htm">gazelle the king of mythical beast</a> [link=http://ezpascal.strefa.pl/mythical-beasts.htm]chimera the flying mythical beast[/link]

DebianPackaging (last edited 2021-08-07 20:01:46 by ClintonEbadi)