Building Debian Packages - The Easy Way

From Koha Wiki
Jump to navigation Jump to search

The process for building custom Debian packages described on this page is obsolete, and will not work out of the box. This process has been replaced by koha-dpkg-docker. See the documentation in that project for details.

Please also see: Building Debian Packages

It provides steps for you to create your own customized Koha packages.

Getting set up

The current packages are being built on a deb10 (buster) system, using a deb10 pbuilder environment (aka chroot)

It's currently recommended to use a deb10 pbuilder chroot

Install pbuilder packages, and create a pbuilder

Install pbuilder 

sudo apt-get -y install devscripts pbuilder dh-make fakeroot debian-archive-keyring

Enable network access for pbuilder 

sudo echo "USENETWORK=yes" >> /etc/pbuilderrc

Create a pbuilder on Debian 

sudo pbuilder create --distribution buster

Or, if you are running Ubuntu and want a Debian stretch pbuilder, you can add a --mirror option, like this... 

sudo pbuilder create --distribution buster --mirror http://ftp.us.debian.org/debian/

Enter pbuilder

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

Log into pbuilder 

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

Install wget and gnupg2 

apt-get update
apt-get -y install \
    ca-certificates \
    apt-transport-https \
    wget \
    gnupg2

So the GPG key can be added: 

wget -O- http://debian.koha-community.org/koha/gpg.asc | apt-key add -

Add Koha package repo to pbuilder 

echo "deb http://debian.koha-community.org/koha stable main" > /etc/apt/sources.list.d/koha.list

Add latest stable npm/gulp/nodejs packages to pbuilder 

echo "deb https://dl.yarnpkg.com/debian/ stable main" > /etc/apt/sources.list.d/yarn.list
   wget -O- -q https://dl.yarnpkg.com/debian/pubkey.gpg \
      | gpg --dearmor \
      | tee /usr/share/keyrings/yarnkey.gpg >/dev/null

echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" \
      | tee /etc/apt/sources.list.d/yarn.list

wget -O- -q https://deb.nodesource.com/setup_18.x | bash -

apt-get update
apt-get -y install nodejs yarn

mkdir -p /nonexistent/.yarn
mkdir -p /nonexistent/.cache/yarn
chmod -R 777 /nonexistent

npm install gulp-cli -g

Check npm/gulp/nodejs package versions

yarn --version
 1.22.19

node -v
 v18.17.1 # needs to be at least version 18

which gulp
 /usr/bin/gulp

gulp -v
 CLI version: 2.3.0
 Local version: Unknown

Exit pbuilder

exit

Clone Koha git repository

Clone the Koha Git repository, (or use an existing koha repo) 

sudo apt-get -y 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 21.11.x, the stable release branch of version 21.11: 

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

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

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"

Patches

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'

Translations

The po files are now no longer part of the main Koha repository and will are built as a separate dependency.

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 21.11.01git -d
  • -r tells the script where to put the packages you build.
  • -v designates the version you are building, using 21.11.01git 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 '21.11 (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_21.11.01-1git+20110522163502.cdf32da0_all.deb
  • koha_21.11.01-1git+20110522163502.cdf32da0.dsc
  • koha_21.11.01-1git+20110522163502.cdf32da0_i386.changes
  • koha_21.11.01-1git+20110522163502.cdf32da0.tar.gz
  • koha-common_21.11.01-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 main, 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 21.11.01git -d

Note: In Koha 23.05 and higher, you can include the CUSTOM_PACKAGE=1 parameter to prevent the build from failing if your package includes custom atomic updates. 

sudo CUSTOM_PACKAGE=1 ./debian/build-git-snapshot -r ~/debian -v 21.11.01git -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_21.11.01-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/21.11.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 21.11.02git -d

Notice the (manual) change from 21.11.01git to 21.11.02git - 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_21.11.02git+20110617001823.a5aa2215_all.deb

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


Developer handbook

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Building_Debian_Packages_-_The_Easy_Way&oldid=34323"