Building Debian Packages - The Easy Way

From Koha Wiki

Jump to: navigation, search
Home > Documentation > Installation > Debian Packages
Koha > Technical > Administration

Building Debian Packages gives you the gory details of how to proceed in order to build Debian packages with an eye to having them included in Debian proper. However, there are some compelling reasons why you might want to create your own packages for your own use, and in that scenario you can get away with being less strict. Luckily, there is a script in Koha called build-git-snapshot, which makes building packages almost painless.


Getting set up

It seems common practice to use a virtual machine (VM) for building packages, so that the process will not interfere with anything else on your machine. So, go ahead and create a virtual machine running Debian 8 (Jessie) with something like VirtualBox. (Setting this up is beyond the scope of this article...)

When you have your VM set up with Debian, you need to install some tools (check debian/ for an up to date list.) Use the oldest distribution that Koha supports if you're planning to build official package.

sudo apt-get install devscripts pbuilder dh-make fakeroot debian-archive-keyring
sudo pbuilder create --distribution jessie

When you are on ubuntu and want debian jessie distribution you can modify last command like this:

sudo pbuilder create --distribution jessie --mirror

Pbuilder will need to get packages from the Koha Debian repository. To access it, you have to add the repository in the pbuilder environment. Login with

sudo pbuilder --login --save-after-login

edit /etc/apt/sources.list.d/koha.list

echo "deb stable main" > /etc/apt/sources.list.d/koha.list

Install wget and gnupg2 first:

apt-get install wget gnupg2

So the GPG key can be added:

wget -O- | apt-key add -

and run

apt-get update

then exit the pbuilder environment


Create a directory for storing the packages you make, so you don't have to look for them in some obscure place afterwards. Create a directory called "debian" in your home directory, for example:

mkdir ~/debian

You also need to clone the Koha Git repository:

sudo apt-get install git
git clone git:// kohaclone
cd kohaclone

Checking out a branch to base your packages on is probably a good idea. Here's how to create a branch that tracks 3.12.x, the stable release branch of version 3.12:

git checkout origin/3.14.x -b 3.14.x

Make any changes to Koha

One reason for building your own packages is that you want to alter Koha in some way compared to the official packages, and now is the time to do it. Just remember that in order for build-git-snapshot to work, you can not have any uncomitted changes in your repository.

Local changes

Make the changes you need and commit them:

vim somefile
git commit -a -m "I changed somefile"


You might want to apply patches that others have created:

wget -O <name_of_patch_file><attachment_number>
git am -3iu <name_of_patch_file>

Alternatively, see for using 'git bz'

Translations (experimental!)

Work is well under way to make the packages work with translations - stay tuned!

Build the packages

Now run build-git-snapshot, making sure you are in the root directory of your cloned repository first:

sudo ./debian/build-git-snapshot -r ~/debian -v 3.14.06git -d
  • -r tells the script where to put the packages you build.
  • -v designates the version you are building, using 3.14.06git for example. Convention is upstream_version[-custom_revision_number][comment] - See debdocs for more information on version numbering. Do not put a - in the name, as Debian interprets that as a revision number you are not allowed to set anymore. You will get dpkg-source: error: can't build with source format '3.0 (native)': native package version may not have a revision. You may use a + though.
  • -d is for debug, which gives you a little more output, so you can see what is happening.

Be patient, building packages does take some time!

When build-git-snapshot is finished, you should have several files in ~/debian:

  • koha_3.14.06-1git+20110522163502.cdf32da0_all.deb
  • koha_3.14.06-1git+20110522163502.cdf32da0.dsc
  • koha_3.14.06-1git+20110522163502.cdf32da0_i386.changes
  • koha_3.14.06-1git+20110522163502.cdf32da0.tar.gz
  • koha-common_3.14.06-1git+20110522163502.cdf32da0_all.deb

The ones you can actually use are the ones that end in ".deb". See Koha 3.x on Debian Squeeze for the difference between koha and koha-common.

Note: When building packages from master, sometime the tests may fail. If you still wish to proceed with a package build, you'll need to prepend the above command with DEB_BUILD_OPTIONS=nocheck, for instance:

sudo DEB_BUILD_OPTIONS=nocheck ./debian/build-git-snapshot -r ~/debian -v 3.14.06git -d

Deploy the packages

Creating your own APT repository

This instructions explain how to manually install the new packages. It is recommended for several reasons that you setup your own APT repository for deploying as explained in Create your own APT repository.

Manual install method

Move the .deb files to wherever you need them, using tools such as an FTP client or the scp command.

When the files are where you want them, you can install them like this:

sudo dpkg -i koha-common_3.14.06-1git+20110522163502.cdf32da0_all.deb
sudo apt-get -f install

This should install koha-common along with all it's prerequisites, along with all the tools it provides, as well as the customizations you added, whatever they were. Congratulations!

(Running sudo dpkg -i will most likely result in a list of errors like "koha-common needs tinymce2 but tinymce2 is not installed". Don't worry, this is taken care of by the next step, sudo apt-get -f install.)

Unmet dependencies

After doing the steps above you might still be missing some dependencies. The best way to get everything correctly installed is to run

sudo apt-get -f install

Updating your packages

After a while you will probably want to create new versions of your packages - because you want to get the latest and greatest bugfixes or you want updated translations or you thought about some more changes you wanted to do to the code.

To get the latest bugfixes, make sure you are in your cloned repository and then fetch and rebase:

git fetch
git rebase origin/3.14.x

As always, remember to commit all your changes! when you are happy with your work build the packages:

sudo ./debian/build-git-snapshot -r ~/debian -v 3.14.07git -d

Notice the (manual) change from 3.14.06git to 3.14.07git - this is so you can tell your packages apart easily.

Now move the .deb files to where you want to use them, and deploy with:

sudo dpkg -i koha-common_3.14.07git+20110617001823.a5aa2215_all.deb

and everything should be taken care of for you, including any necessary changes to the database.

Developer handbook

Personal tools