Building Debian Packages - The Easy Way
From Koha Wiki
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/README.build 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
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
echo "deb http://debian.koha-community.org/koha stable main" > /etc/apt/sources.list.d/koha.list
Install wget first:
apt-get install wget
So the GPG key can be added:
wget -O- http://debian.koha-community.org/koha/gpg.asc | apt-key add -
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:
You also need to clone the Koha Git repository:
sudo apt-get install git git clone git://git.koha-community.org/koha.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.
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> http://bugs.koha-community.org/bugzilla3/attachment.cgi?id=<attachment_number> git am -3iu <name_of_patch_file>
Alternatively, see https://wiki.koha-community.org/wiki/Git_bz_configuration for using 'git bz'
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:
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.)
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.