Updated on April 3, 2023
The first two sentence from the Debian Packaging Tutorials Page are:
"Debian Packaging is an art. The available tools evolve constantly, and so must your packages to follow the evolution of the Debian Policy."
In other words, your source code might successfully compile and build into a Debian Package today, and tomorrow, it will fail because of a Debian Policy change. Debian refers to their Policy as a standard. It only gets stricter. As of April 3, 2023, Debian's Policy Standard is at version 4.6.2.0.
I refer to this as Debian's Cool-Aid. Presently, I do not like the taste of Debian's Cool-Aid. Hopefully, overtime, I will acquire a taste for it.
Debian package names conform to the following convention:
Although, I have not seen this explicitly stated anywhere, error messages indicate that it does not like capital letter in the package name.
Thought this tutorial, foo will be used for the simple package name and arm64 will be used for the Architecture Code.
The source code for Debian packages is supplied in three files:
Note the first file does not contain the Debian revision #.
To decompress both tarballs:
dpkg-source -i foo_ver#-rev#.dsc
The original source code will in the folder:
Note the underscore was changed to a dash.
In the foo-ver# folder will be the original source code and a subfolder "debian". The subfolder contains the files necessary to make a Debian package from the source code.
Debian expects you to use the "debhelper" package to create Debian packages:
sudo apt install debhelper
Before you make any changes, you should ensure that you can create a Debian package from the original source code. Make sure you are in the source code folder and execute:
debuild -uc -us
If successful, a Debian package file will be in in the parent folder of the source code:
foo_ver#-rev#_arm64.deb
There should also be three other files in the parent folder.
Now, run "debuild -uc -us again. If this fails, it is because something in the "Makefile" which was called by debuild, modified something in the source code folder, and it was not properly cleaned by "make clean". "make clean" is called by "debuild" before "debuild" checks to see if there are any modifications to` the source code. For example, Makefile will create binary object files in the source code folder, and these must be removed by make clean or else the source code is said to be dirty.
Debian does not allow the "Makefile" or you to directly modify anything in the source code folder, foo-ver#. To enforce this, the foo_ver#-rev#.dsc contains a 256-bit checksum of foo_ver#.orig.tar.xz.
Debian only allows you to change anything in the original source code via patch files. This includes insertion, deletion and modifications of files. Patch files are in the subfolder "debian/patches".
Patch files are managed by "quilt", which was installed when you installed "debhelper". To modify a file, execute:
quilt new "your_new_patch_name.patch"
quilt add "file_name-you-want-to-modify"
Use your favorite editor to modify the file, then execute:
quilt refresh
You can edit and use quilt refresh multiple times.
If you want to insert a file. Copy the file to the location where you want to insert it. Then, use the Linux diff command to generate a patch file:
diff -Nru /dev/null file-to-add >your_new_patch_name.patch
Before your patch file, which will add a file to the source code, can be imported into quilt, you must remove the file, to be added by quilt, from the source directory.
quilt import your_new_patch_name.patch
quilt push your_new_patch_name.patch
Note, every time you successfully build a Debain package it will create a new foo_ver#-rev#.debian.tar.xy file and a new foo_ver#-rev#.dsc file with an updated checksum for foo_ver#-rev#.debian.tar.xy
If your source code is dirty after using "debuild", one way to clean it is:
tar -xvf foo_ver#.orig.tar.xy
This will restore the original source code, but it will not alter your modifications in the subfolder "debian".
You also change the name of the package in the control file.
If you think we are drinking Debian's Cool-Aid, you have only had your first taste. There is more to come.
Inside the subfolder, "debian", there must be two files:
The rules file is an executable script file. It makes sure that source code complies with the Debian Standard for Packages. The Debian Standard for Package gets updated often so there are numerous versions. The version that the source code needs to comply with is specified in the control file. However, Debian wants to always use the latest version and use overrides in the rules file. To do this, you need to be familiar with the latest Debian Standard for Packages and familiar with the source code, which you did not write! Debian is also going to require man pages and changelogs files.
I am not drinking any more of the Debian Cool-aid! However, there is more:
If the source code depends on other Debian packages, Debian expects you to install the package development utilities for the dependent packages so Debian can check the source code to make sure it conforms to what is in the dependence packages dependance utilities.
But Debian is going to help you to conform by using "lintian" to modify your code. Again, "lintian" is part of the "debhelper" package. Thankfully, you can override it:
debuild -uc -us --no-lintian
Almost everything in the rules file can be overridden. So for an older Debian package, there will probably already be numerous overrides in the rules file. This can get very complicated very fast.
The control file contains the dependencies and package name and other information.
The beginning of the control file contains the dependencies to build the package. For example:
After the package name are:
Most packages have an install file in the subfolder "debian":
This file specifies the location of where to install the driver files. For example, binary files are usually installed in /usr/bin and man pages in /usr/share/man.
There may also be a not-installed file that specifies which files are intentionally not installed.
The Debian Packaging Framework is not compatible with all Debian Packages. However, Debian will use it anyway and force everyone to use it. For example, the Debian's "printer-driver-foo2zjs" will only successfully "debuild" the first time. This is because every time "debuild" is run, it looks online for updated printer ppd files, and if it finds updated ppd files, they will replace the old ppd files in the subfolder "PPD". Hence, after the first "debuild", the subfolder PPD is dirty. You have to manually restore the old ppd files before you can successfully run "debuild". There are two other problems with the particular driver. "foo2ddst.o is not removed because of a typo: "foo2dsst.o" instead of "foo2ddst.o". In addition, there are two symbolic links in the subfolder "foomatic-db" that are not cleaned; they are "db" and "source".
In order to build a Debian package, you are going to have to install a lot of Debian programs on a computer. I have not figured out if or how you can cross compile and build a Debian package for different computer architectures and OS's. Hence, you may have to set up numerous computers and compile and build the package for each architecture i.e., armhf (32-bits), arm64, amd64, etc. What a pain in the butt!
If you are just wanting to modify a package for your personal use, my advice is, when possible, leave the rules and control files alone. Yes, you will have to drink some of Debian's Cool-Aid, but you do not have to drink all of it. However, if you want to send your modification(s) to Debian for consideration into a future release, then you will probably have to drink all of Debian's Cool-Aid.