Basics of Debian Packages

Debian packages are easy installation packages for Debian or Debian-based distributions. This tutorial is divided into two parts; the parts Verification & Installation are destined to any user, and the parts Getting the package's code & How to Build to programmers or more advanced users.

Verification

Most GNU/Linux software is Libre Software, which means anyone can take its source code, modify it, and redistribute it. While this is a strength, it also opens the door for potential abuse — like inserting malicious changes. That's why verifying the package you're installing is important.

The most common way to verify a package is by checking its SHA hash.

What is SHA verification?

An SHA (Secure Hash Algorithm) creates a sort of digital fingerprint of a file. When a package is created, a hash is calculated. If the file changes — even by a single byte — the hash will be completely different. So, by comparing the hash of your downloaded file with the one provided by the developer, you can confirm whether the file was modified or not.

Repository vs Manual Downloads

If you've installed software on GNU/Linux before, you probably did it using a software repository — either through a graphical app store or by using commands like apt install. When you install this way, the system automatically checks the integrity and authenticity of the packages in the background.

However, if you manually download a .deb file from a website, those automatic checks don't happen. In this case, it's crucial to verify the file yourself using the SHA hash.

How to check it

Here are the steps to verify the SHA sum of a package:

1. Download the .deb file.
2. Find the expected hash (usually listed on the download page).
3. Run this command in the terminal: echo "<expected_hash> <file_path>" | sha256sum --check

If it says OK, it means the file matches the one provided by the source.

A note about signatures

Before 2016, Debian packages could be signed and directly verified using GPG signatures. But the Debian teams, updated the architecture of the packages & repositories, and since then individual .deb files are not directly signed.

Instead, developers sign the package set when they upload it to the official Debian repository. This signature is used to verify the repository's index files and after that, when you install a package, only its SHA hash is verified — the hash listed in the index is compared to the one of the downloaded file.

Installation

To install Debian packages, it is necessary to use a package manager (Ex: from a root terminal use dpkg -i /path/to/the/package/). In some distributions it's even possible to avoid using the terminal and install them by double-left-clicking.

Personally, I rather do the installation from the terminal because sometimes the packages display messages (errors, warnings, etc...) that get hidden in graphical interfaces. It really depends on the distribution and the package manager, but in any case doing it from the terminal will always give you the maximum amount of information.

When doing a local installation (installing a package that doesn’t come from a repository), the dependencies aren’t automatically installed. The terminal output is then like the following:

root@debian:/home/user/Downloads# dpkg -i 1.6-7zRecover.deb
 Selecting previously unselected package 7zRecover.
 (Reading database ... 105435 files and directories currently installed.)
 Unpacking 7zRecover (from 1.6-7zRecover.deb) ...
 dpkg: dependency problems prevent configuration of 7zRecover:
  7zRecover depends on p7zip; however:
   Package p7zip is not installed.
  7zRecover depends on python-psutil; however:
   Package python-psutil is not installed.

 dpkg: error processing 7zRecover (--install):
 dependency problems - leaving un-configured
 Errors were encountered while processing:
 7zRecover

In this case I installed 1.6-7zRecover.deb and the dependencies p7zip and python-psutil are missing. To fix them, the command apt-get -f install is handy. It will try to fill the dependencies by using the available repositories.

If after using the previous command, the dependencies aren’t installed, it means that the repositories don’t have the missing packages. You can then manually install them or add a repository.

The steps for adding a repository are the following:

1. Add the repository into /etc/apt/sources.list.d/debian.sources, or create a new file.
2. If the repository is PGP signed:
   1. Download the developer's PGP key and add it to your trusted keys curl -fsSL https://example.com/repo-public.gpg | gpg --dearmor -o /usr/share/keyrings/example.gpg
   2. Link the PGP key to the repository block, with the following line Signed-By: /usr/share/keyrings/example.gpg
3. A repository block should look like the following:

   Types: deb deb-src
   URIs: https://deb.debian.org/debian
   Suites: bookworm bookworm-updates
   Components: main non-free-firmware
   Enabled: yes
   Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

4. Update the software list: apt-get update
5. Install the missing packages: apt-get -f install

Getting the package's code

Debian packages are basically divided into two contents; the software's files and the information for the package manager.

• To get the software files, it is only necessary to decompress the package with any decompression tool like p7zip, ex: 7z x /path/to/the/deb.
• To obtain the package manager information, it is necessary to use dpkg, ex: dpkg -e /path/to/the/debian.

Some distributions allow extracting the package by doing right-click > decompress and sometimes even both parts are extracted.

How to build

The right way of building a Debian package is by using dpkg-buildpackage, but it may be a little bit complicated. Instead, it is possible to use dpkg -b <folder>. These are the basics for creating Debian packages with dpkg -b <folder path> for any binary or interpreted language (Python, Bash, etc..):

1. Create a DEBIAN files & folders structure

   ProgramName-Version/
   ProgramName-Version/DEBIAN
   ProgramName-Version/DEBIAN/control
   ProgramName-Version/usr/
   ProgramName-Version/usr/bin/
   ProgramName-Version/usr/bin/executable_script

   Here is an example of the control file. To create it, paste the following text into an empty file:

   ProgramName-Version/DEBIAN/control

   Package: ProgramName
   Version: VERSION
   Architecture: all
   Maintainer: YOUR NAME <EMAIL>
   Depends: python3 (>=3.10), etc,
   Installed-Size: in_kb
   Homepage: https://foo.com
   Description: Here you can put a one line description. This is the short Description.
    Here you put the long description, indented by 1 space.

   Remarks:

   • The folder structure will be the structure of the program once it's installed.

   • Scripts placed at /usr/bin/ are directly called from the terminal, and their extension should not be added. This is the location where the main executable must be placed.

     As a general rule, if the program has multiple files, they should be placed under ProgramName-Version/usr/share/ProgramName/all the files.

     For more information about this, you can read about the GNU-Linux structure since there are many locations for different stuff. For example, if the package is a python library, you will probably not have a script in /usr/bin/ and the python module shall be added to /usr/lib/pythonX.X/site-packages/python_module.py.

   • It is possible to add pre-installation, post-installation, pre-removal scripts to the package. They only need to be added inside the DEBIAN folder with their respective name (preinst, postinst, prerm, etc..).
   • For adding a graphical launcher (application icon), it is only necessary to create a program_name.desktop file into the applications folder /usr/share/applications/. To figure out the content of the file, sniff the files of your system's application directory, and you will probably find good examples.

2. Change all the folder permission to root

   chown root:root -R /path/to/ProgramName-Version

3. Change the script's permissions to executable

   chmod a+x /path/to/the/scripts

4. Finally, build the package

   dpkg -b /path/to/the/ProgramName-Version

How to automate the build

Doing all the previous steps and filling the control file can become annoying and time-consuming. That's why I created build-deb , it allows easily creating packages without doing any effort.