Skip to content

How to do KERN packaging

Jump to bottom
Gijs Molenaar edited this page Dec 20, 2018 · 21 revisions

Introduction

for reference, here you can find most related documentation:

Preparations

  1. Install git-buildpackage:
$ sudo apt install git-buildpackage

  1. Decide for which KERN version you want to make the package. You need access to a system running a version equal to the target KERN platform, for example Ubuntu 18.04 for KERN-4. If you don't have access to such a system you might want to try pbuilder..

  2. You need a placeholder on your for all your packaging. For this tutorial I assume you build all your packages in ~/packaging:

$ mkdir ~/packaging

Create a new KERN package

  1. create a new repository in the kernsuite-debian organisation with the same name as the package. If you don't have admin access in this organisation create a repository under your own private github account and open an issue on the kernsuite issue tracker to request the creation of the repository.

  2. Create a new git repository on your build system with the same name as your package. For this tutorial I assume you want to pack the foobar package version 0.1:

$ mkdir ~/packaging/foobar
$ cd ~/packaging/foobar
$ git init
  1. Download the ORIGINAL unmodified tarball of the software, and put it in ~/packaging. make sure it is named following this syntax: foobar_0.1.orig.tar.xz. That is <package>_<version>.orig.tar.<compression>. If the maintainers of the original source code don't do proper released of the software, you could make a date based release yourself. Note that this is the last resort, it is much better to base the package on a versioned source tarball. To make your own package just make a checkout of the upstream repository, remove any tempory or git files, and put that in a tarball. For example for psrchive:
$ cd ~/packaging
$ git clone --depth=1 https://git.code.sf.net/p/psrchive/code psrchive
$ cd psrchive
$ git log --date="format:%Y%m%d" --pretty="0.0~git%cd.%h"   # check the date of the last commit, write this down
$ cd ..
$ rm -rf psrchive/.git*
$ tar Jcvf psrchive_2012.12+git20180308.tar.xz psrchive   # where 20180308 is the date from the last commit.

In this case, 2012.12 is the last versioned release of psrchive. If the upstream repository doesn't have any repeases yet the base version should be set to 0 (0+git20180308). The + sign is a Debian trick to append subversioning to the upstream versioning schema. using this method we are sure the Debian package manager will always update to the latest version of the package. Read more about Debian versioning in the versioning section of the debian maintainers guide.

  1. import the original tarball into your new version repository:
$ cd ~/packaging/foobar
$ gbp import-orig ~/packaging/foobar_0.1.orig.tar.xz
  1. Now it is time to add your Debian metadata. You can do this manually by copying the debian files from an other package or the empty package template, but I recommend using the debmake command. The debmake command might need some helper flags to find the original tarball:
$ cd ~/packaging/foobar
$ debmake -u 0.1 -z tar.xz
  1. Now go into the package and update all the required files! If you don't know what to do it is time to start reading the Debian maintainers guide.

Update existing package

  1. Fetch our Debian package github repository. For this tutorial we assume you want to update foobar.
$ git clone https://github.com/kernsuite-debian/foobar
$ cd foobar
  1. Check if there is a new release available. If the project has a debian/watch file, you can do this automatically:
$ gbp import-orig --uscan

If there is no watch file and the upstream project does regular releases add a [watch file (https://wiki.debian.org/debian/watch). This makes updated the package much easier. If the upstream project doesn't publish releases there is currently no point in creating a watch file, the git checkout tarball needs to be created manually.

note: If you are running Ubuntu Xenial you need to have at least git-buildpackage 0.8.18 installed, otherwise gbp dch doesn't generate the right signature (ignores DEBEMAIL and DEBFULLNAME). You can find a copy of the right version in the kernsuite debian organisation

note2: To update repositories that don't do versioning but monitor a upstream git repository you need to have the devscripts package >=2.18. Ubuntu bionic comes with 2.17, so you need to build a package yourself from https://salsa.debian.org/debian/devscripts. I didn't upload it to the KERN archive since it is not a astronomy package and I dont want to override this kind of packages for everybody.

If you are in a rush you can also download the package manually and put it in your package folder as for example ~/packaging/foobar_0.2.orig.tar.xz.

  1. increment version number using gbp dch. Make sure release is set to xenial, or whatever the platform is you are packaging for. The version number depends a bit on the package but the rule of thumb is start with <upstream_version>-1kern1, and then continue with <upstream_version>-1kern12 of you made a mistake and want to fix the package itself. <upstream_version>-1kern2after that, etc. Counting is reset to<upstream_version>-1kern1` in case of an upstream release. We do this to be as compatible as possible with Debian packages. Some of our packages are or will be part of Debian at some point.

Building the package

  1. check if the package builds with gbp build-package or dpkg-buildpackage. You can add the --git-ignore-new flag to ignore temporary changes.

  2. To make sure everything builds on launchpad you could build inside an empty system to make sure the build dependencies are right. Your system probably has all kind of packages installed, so it is wise to do it in a chroot. Debian has all kind of funky utilities for this, for example:

    https://pbuilder.alioth.debian.org/

    quick start:

    • pbuilder --create to create a chroot
    • pdebuild to build source package in chroot
    • You probably need to add the kernsuite PPA as a dependency to your chroot https://pbuilder.alioth.debian.org/#usingspecialaptsources. I've prepared example pbuilder configuration. Note that you need to supply this config file every time you run pbuilder. You can also copy it to ~/.pbuilderrc to use it every time. Don't forget to edit the paths inside the file.

    Note that you don't have to use the chroot, it is just to make sure everything works. If changes are minimal al quick build test could be enough.

  3. I use this long command to automatically to combine all steps in one go:

$ BUILDER=pbuilder gbp buildpackage \
             --git-pbuilder \
             --git-pbuilder-options="--buildresult /packaging/kern/packaging/repo \
             --configfile /packaging/kern/packaging/pbuilderrc "
  1. check if the package installs. Preferably in an empty system, virtual machine or docker image.

Uploading changes to github and launchpad

  1. If everything looks awesome commit your changes in a new commit on master.

  2. Make sure the changelog entry is correct, specifically the version and target platform (xenial, bionic, not UNRELEASED).

  3. If you are absolutely sure everything looks good tag the current state:

$ gbp build-package --git-tag

Note that you can also add the --git-tag flag to long BUILDER=pbuilder command above.

  1. run git push --all --follow-tags to upload all your changes to GitHub. If you don't have direct access to the repository, clone the packaging repository on Github, push to the clone and issue a pull request. You need to do 2 pull requests, one for the master branch and one for upstream.

  2. run gbp buildpackage -S -sa for building a source package in the parent. It should generate a file that looks like `../foobar_0.2-1kern1_source.changes

  3. run dput ppa:kernsuite/kern-dev ./foobar_0.2-1kern1_source.changes to upload the package to the Kern Suite dev repo.

Clone this wiki locally