Packaging using gbp - sillsdev/FwDocumentation GitHub Wiki

Table of Contents Overview Cloning the repo Adding a new patch Converting an existing source package to a `gbp` repo Starting a new project from scratch Additional notes Further information

Overview

gbp or [https://honk.sigxcpu.org/piki/projects/git-buildpackage/ git-buildpackage] is a utility that supports maintaining a Debian/Ubuntu package in git. It takes care of a lot of the details and ensures consistency and correctness.

gbp is only for quilt packages (ones that have a segmented version number and potentially have patches against the upstream source). For native packages (which have a single tarball instead of separate orig and debian tarballs) gbp doesn't provide anything of value and it's better just to use git directly.

A gbp-compatible repository has two main branches:

upstream
master

The upstream branch is used to store the content of successive upstream ('orig') tarballs, and each upstream release is tagged.

The master branch is forked from upstream and adds the debian/ directory. It has tags for each package release.

When a new upstream version is integrated, the upstream branch is merged into master.

There's usually also a pristine-tar branch that's used in conjunction with upstream to recreate exact copies of the original upstream tarballs.

Some of our packages are modifications of existing Debian or Ubuntu packages and use a fork of the upstream gbp repo. In this case, it's necessary to use a branch other than master for our versions, and we usually use a branch name sil for this. This requires passing a '''--git-debian-branch='''''branchname'' option to gbp to tell it which branch to use. This is noted when it's relevant in the following descriptions.

Cloning the repo

Our package repos are on git.lsdev.sil.org rather than github and have URLs of the form

ssh://git.lsdev.sil.org/srv/git/lsdev/public/debian/''PACKAGE'' (read-write)

and

git://git.lsdev.sil.org/debian/''PACKAGE'' (read-only)

Although they can be cloned with the regular git command, it's better to clone them with gbp because this will set up the right branches:

    gbp clone --pristine-tar ssh://git.lsdev.sil.org/srv/git/lsdev/public/debian/''PACKAGE''

If a branch other than master is being used for packaging, as explained above, then an additional '''--git-debian-branch='''''branchname'' option will need to be included in the command above.

Adding a new patch

Instructions to add a patch modifying the project source code. (Note: This is not the right thing to do if you are just modifying files in debian/.)

For a quilt-format package, differences from the upstream release are stored as a series of patches in debian/patches/. gbp can import these patches into a temporary branch called a patch-queue which is never pushed to the shared (remote) repository. The developer then makes new commit(s) on this branch, and uses gbp to export the branch back to debian/patches/. The updated debian/ directory is then committed to the master branch.

The exact steps are as follows:

git checkout master

Start from a known state

gbp pq import

Turn the patches into commits on a temporary branch and switch to it. You are now on patch-queue/master

HACK, COMMIT, HACK, COMMIT, HACK, COMMIT ...

Your commits will become new patches

gbp pq switch

Switch away from the patch-queue branch back to the main branch

git status

Check for extraneous files and uncommitted changes

git clean -dxf

Remove extraneous files

gbp pq export

Update debian/patches/

git status

Review the added/changed patches

git add debian

Stage everything under debian/

git commit -m "Add patch(es): ..."

List the patches in the commit message

gbp dch -R -c

Update the changelog and open it in an editor for final adjustment. On Debian you can usually just save and quit. When working on Ubuntu, remove the 'ubuntu1' suffix and increment the package number at the end of the version. Change the release code from precise/trusty/xenial to 'unstable'.)

gbp buildpackage --git-pristine-tar --git-tag -nc -S

Build a source package

If the branch being used for packaging is not master but some other branch (eg sil) then above procedure needs to be modified slightly. As well as replacing all references to master with the actual branch name, the dch and buildpackage commands will need an extra parameter:

gbp dch -R -c '''--debian-branch=''branchname'''''
gbp buildpackage --git-pristine-tar --git-tag -nc -S '''--git-debian-branch=''branchname'''''

Note that the two commands use differently-named options!

When you've built and tested the package, please remember to push your changes (including tags) to origin.

Converting an existing source package to a `gbp` repo

Importing an existing Debian package into a new Git repository is as easy as:

    gbp import-dsc --pristine-tar ''package''_''version''.dsc

This will create the git repo and set up all the right branches and tags.

It's possible to reproduce some of the history by importing several previous versions of the source package at once:

    gbp import-dscs --pristine-tar ''package''_*.dsc

See the section titled Importing already existing Debian packages in the manual for full details.

Starting a new project from scratch

Sometimes we need to create packaging for an upstream project that doesn't have a Debian or Ubuntu package yet. gbp makes this particularly easy.

Make a directory for the package:

    mkdir ''package''
    cd ''package''
    git init

Then import the upstream tarball:

    gbp import-orig --pristine-tar -u ''version'' ''tarball''

Finally, create (a draft of) the debian/ directory:

    dh_make -p ''package''_''version''

See the section titled Starting a Debian package from scratch in the manual for full details.

If the upstream project is on github and has tags, you can create the package directly from github, without a tarball, using the following script:

    PROJECT=${1?} VERSION=${2?}
    
    OWNER=${PROJECT%/*}
    PACKAGE=${PROJECT##*/}
    
    mkdir -p $PACKAGE
    cd $PACKAGE
    git init
    
    cat >watch <<EOF
    version=3
    opts="filenamemangle=s/(?:.*?\/)?v?(\d[\d.]*)\.tar\.gz/${PACKAGE}_\$1.orig.tar.gz/" \
      https://github.com/$PROJECT/tags (?:.*?\/)?v?(\d[\d.]*)\.tar\.gz
    EOF
    
    uscan --package $PACKAGE --upstream-version $VERSION --watchfile watch --force-download
    
    gbp import-orig --pristine-tar --no-interactive ../${PACKAGE}_${VERSION}.orig.tar.gz
    
    dh_make -p ${PACKAGE}_${VERSION}
    
    mv watch debian/

This uses a watch file, which defines a URL pattern that's used to obtain upstream source tarballs directly. The package can later be upgraded very simply to a new upstream version with:

    gbp import-orig --pristine-tar --uscan

The script uses the watch file with uscan command to get the initial tarball, which ensures that the watch file is correct.

Additional notes

It's also possible to pull from an upstream git repository directly, without using tarballs, by forking the repo and adding a debian/ directory. See the section named When upstream uses Git in the online documentation for full details.
gbp can run pbuilder builds directly, but we're not set up for that currently.

Further information

http://wiki.debian.org/PackagingWithGit
http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html
file:///usr/share/doc/git-buildpackage/manual-html/gbp.html

Packaging using gbp - sillsdev/FwDocumentation GitHub Wiki

Table of Contents