In this article you’ll learn how to package software for the Debian ecosystem: Debian, Ubuntu (and family), Mint, etc!
The two most common reasons for wanting to create a Debian package are to distribute software you created (or you belong to a software project) or you want to ease the burden of installing software for others (for example friends, family, or clients). However this task can seem daunting and confusing, but rest assured it is actually quite easy if you follow the provided steps.
It should be noted much of this process may be performed using GUI tools like a file manager (Caja) and text editors like (Pluma). Still you’ll eventually have to run commands. Therefore this guide is going to contain shell (sh/bash/etc) commands. Also order doesn’t matter (for the most part) and some steps may be combined. However in the interest of explaining and teaching steps have been broken up and the order is what it is.
Step 1: Create the project’s home directory
This first step is to create a directory to hold new project (software) files. There really is no right or wrong place to put these files. However you should ideally approach this with organization in mind.
For this example we will create a directory called newapp in our home directory.
shell> mkdir -p ~/debpkgs/newapp
The -p flag will create the directory debpkgs if it doesn’t exist. That way we are keeping our projects nicely arranged, but again this is all up to you.
Step 2: Create the DEBIAN directory inside the project’s home directory
The DEBIAN directory holds special files to control the setup process and important information. This directory is reserved for the system and may not be used for your actual project files.
shell> mkdir ~/debpkgs/newapp/DEBIAN
Note: if you want to combine Steps 1 and 2 you could just run:
shell> mkdir -p ~/debpkgs/newapp/DEBIAN
This will create the DEBIAN directory and the newapp directory in one.
Step 3: Copy files into the project home directory
Now you need to copy any and all files that will be installed (added) to the system by the package. This may include one, tens, hundreds, or thousands of files. However you need to do this in a specific way or it won’t work correctly.
The project home directory, in this case ~/debpkgs/newapp, becomes the root or / when the package is installed. So you need to create the final structure inside the project’s home directory.
This means if you want a file to be installed in /usr/bin/ you need to create /usr/bin/ inside the project’s home directory.
~/debpkgs/newapp/usr/bin/
Now place the file(s) to go into /usr/bin/ inside that directory.
If you want a file to be installed into /opt/newapp/ you need to create /opt/newapp/ inside the project’s home directory.
~/debpkgs/newapp/opt/newapp/
Now place the file(s) to go into /opt/newapp/ inside that directory.
Since there is no way to know the desired layout of your project this is as far as this guide may assist. However as stated there is no limit. Also make sure you verify the file permissions as they should carry over when installed.
Step 4: Create the control file
The control file is what sets important parameters for your project. This includes items like the name, version number, maintainer, dependencies, etc. So let’s create it.
shell> touch ~/debpkgs/newapp/DEBIAN/control
Step 5: Alter the control file
Now the control file should be edited to add the necessary information. There are some required fields like Package (name of project), Version, and others. Still there are many that are optional. Below is a good balance of required with some optional fields.
- The package name may contain lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). Also you should respect other package names and avoid name collisions to the best of your ability.
- Depends is where you list required dependencies. So if your application requires other packages list them. If you have multiple ones they are separated by a comma and a space. You may also declare a minimum version.
- View the full list on Debian’s site (new window)
shell> vi ~/debpkgs/newapp/DEBIAN/control
or
shell> nano ~/debpkgs/newapp/DEBIAN/control
Now copy and paste the following (stopping before Step 6 text) and alter/edit to your project. Then save and close the control file. Steps 4 and 5 may be combined into one as text editors will create the file if you name it control when saving.
Package: newapp
Version: 1.0
Architecture: all
Essential: no
Priority: optional
Depends:
Maintainer: My Name
Description: This is the best app in Linux.
Step 6: Build The Package
It is time to build the package. This is very easy. However the system will place the new package in our current directory so it is recommended you switch to your package’s parent directory. In this case debpkgs. You should note you can not build a package when inside the package’s home directory.
shell> cd ~/debpkgs/
Now let’s build the package itself (it is minus minus build or dash dash build):
shell> dpkg-deb –build ~/debpkgs/newapp
If all went well you’ll have a new package. The directory name (in this case newapp) will be used appended with dot deb. If there are any errors the system will display them.
Step 7: Testing The Package
You should always test install a package including after changes to ensure it works as desired. It is highly recommended you use a virtual machine for testing in case something goes wrong. Plus taking a snapshot before the install will allow you to install the package over and over quickly and easily.
There are many ways to install a package. This includes with GUI package managers or using the command line. If your project has dependencies and you want install from the command then gdebi is recommended.
shell> gdebi newapp.deb
or
shell> dpkg -i newapp.deb
You should keep in mind that you may need sudo permissions depending on your application.
Step 8: Updating, PreInstall, & PostInstall
Now that you have a working package you probably have a few questions:
1) How does updating work?
2) What if I need something done before or after installing the files? For example you want to remove an old version before installing, want to create data directory after installation, stop a service before install, start a service after install, etc.
Let’s review these scenarios…
Updating:
When you need to update your project you simply add or replace existing files in your project’s home directory and recreate the deb file. When the deb file is reinstalled/upgraded it will replace any existing files with your updated ones. Of course you should update your control file with the new version number and any new dependencies. Also you may need to alter the description.
However you may be saying what if I need to remove a file? This is where the PreInstall and PostInstall functions come in action. Also don’t forget when updating versions you may need to update the PreInstall and/or PostInstall file(s).
PreInstall (Optional):
You see a basic deb package is really just copying files from the project to the system. That is really all it does. However what if you need to perform an action other than copying before installing your package files? As mentioned above say remove a file(s) or directory(ies) or create a directory for data or stop a service.
Well it is possible using a special file called preinst that has executing permissions turn on placed in the DEBIAN directory. This is just a shell script so shell or BASH programming is used.
Create the file:
shell> touch ~/debpkgs/newapp/DEBIAN/preinst
Turn on execution bit:
shell> chmod +x ~/debpkgs/newapp/DEBIAN/preinst
Now edit the file to add the necessary shell instructions. Since this varies by the project this guide is unable to assist further.
PostInstall (Optional):
This works similar to the PreInstall method above only these instructions will be called after installing your package files. For example you may want to create a directory for data or start a service.
A special file called postinst that has executing permissions turn on is placed in the DEBIAN directory. This once again is just a shell script so either shell or BASH programming applies.
Create the file:
shell> touch ~/debpkgs/newapp/DEBIAN/postinst
Turn on execution bit:
shell> chmod +x ~/debpkgs/newapp/DEBIAN/postinst
Now edit the file to add the necessary shell instructions. Since this varies by the project this guide is unable to assist further.
Final Notes:
It should be noted that there are several other configuration files. This guide does not claim to cover all the options. Still using the above steps it is easy to get a deb package built and working. Also as stated you should always test, test, and test your package again. It is important you get your packages correct especially if you are removing or altering data. Also you should respect others’ projects and ideally follow “proper” Linux file structure lay out.
If you require professional assistance or don’t want to deal with creating deb packages you may contact us for paid support.