How to modify and rebuild a package for Ubuntu MATE (or Ubuntu, or Debian)

Why Did You Post This?

Lately I've created a lot of patches for various MATE applications, usually by request of another user here who asks for a developer to change something. I can and usually do contribute my changes upstream (to the main MATE developers), but alas it takes a long time for a new version of MATE to get released, and even longer for the new packages to wind up in Ubuntu MATE. As such I often distribute patches to users who can't wait ~6 - 12 months for a feature they need now to be made official.

But patches pose a problem: How do you use them to modify software that's already installed and built on your system? After all, patches are not executable code in and of themselves; they are a list of modifications -- a laundry list, if you like -- to be applied to a program's source code; after modification by the patch, the source code is what gets built into a usable form, and then voila! -- you can take advantage of the unofficial feature addition.

This doesn't sound too difficult, and indeed it's really not. But there are few (if any) up-to-date or complete guides on installing software from source anymore. To cut to the chase, I'm too lazy to write the instructions in every single post I make on the subject, so I'm writing it here. (Laziness is a virtue, is it not?)

One final thing: If somebody notices a flaw in my guide here, please let me know. The only thing worse than no information at all is information that looks useful, but is total garbage in reality. Ask me how I know that. :stuck_out_tongue:

Obviously, most of these steps require you to enter commands into the Terminal. Be prepared to enter some commands -- quite a few of them.

What is the name of the package in question?

As odd as that question may sound, it's a highly important question. If you don't know what the standard package name for the application you want to build, you need to find it out now, because we'll be using that name multiple times throughout this tutorial.

You can search the APT database for the name of the package in question using apt search [keywords]. Let's say you didn't know what the Ubuntu package for the MATE Panel was named. Run apt search mate panel and it'll tell you, albeit among a whole pile of other similarly named packages (Debian has over 59,000 packages available and it really shows!):

mate-panel/stable,now 1.20.5-1 i386 [installed]
  launcher and docking facility for MATE

So the package name is mate-panel. What a tricky name! :slight_smile:

Prerequisite: Enabling the Source Repositories

Before you start using any source code, you first need to ensure you can get the source code for the package in question. You'll need to uncomment a few lines in the APT package manager's sources.list file, which dictates to APT which servers and directory paths to install software from. This step is fairly simple to do.

Run the command sudo pluma /etc/apt/sources.list. This will open a text editor window where you can manipulate the sources.list file.

Now, if you haven't modified the sources.list file since you installed the system, you'll likely see blocks of lines like these:

deb focal main restricted
# deb-src focal main restricted
## Major bug fix updates produced after the final release of the
## distribution.
deb focal-updates main restricted
# deb-src focal-updates main restricted

Uncomment (remove the leading # from) any line which begins with deb-src which is preceded by a similar deb line that is not commented out. Don't bother uncommenting any deb-src line which does not have an uncommented deb equivalent immediately above it; so for example, don't uncomment the deb-src line in the following block:

## Uncomment the following two lines to add software from Canonical's
## 'partner' repository.
## This software is not part of Ubuntu, but is offered by Canonical and the
## respective vendors as a service to Ubuntu users.
# deb focal partner
# deb-src focal partner

On a default installation of Ubuntu MATE 20.04, the only instances of deb-src you need to uncomment are first through the seventh instances, inclusive. You can also use the Find tool of Pluma to search for # deb-src, if that would make the job easier.

When you are done, save the file and close Pluma.

Update the package database

Don't overlook this step! If you made any modifications to the sources.list file in the previous step, then you must execute this step no matter what else. You will most likely run into unforeseen errors further down the line if you don't do this.

Execute: sudo apt update. This should take at most a few minutes.

Important: Create a new temporary folder

The build process will create a lot of files to say the least. It's generally a good idea to segregate the build process's files from your various other documents, just to reduce confusion. When was the last time you took apart a Swiss-made watch with tiny screws over a haystack? If you ever have done that, chances are something went wrong and you lost a few screws. Honestly, keeping things clean will pay off in the long run.

Without further ado, create a new directory and "change directory" into it:

mkdir BUILD

Of course, you can choose a different name for the directory than just BUILD.

Get the package's build dependencies and assorted necessary tools

Now you need to get the packages that the MATE Panel, for instance, depends upon. More specifically, you need to get the versions of the packages generally reserved for software developers so that they can compile software. This is a simple task:

sudo apt build-dep [package name]

Obviously, replace [package name] with the name of the package you want to rebuild.

After that, make sure you have some essential utilities installed:

sudo apt install build-essential devscripts

Get the package's source code

Now it's time to get the source code for the package in question. Execute:

apt source [package name]

Play around with the source code

Change directory into the location of the source code. Generally speaking (but not always) the source code is located in a directory named after after the package name, followed by a version number. Type cd [package name] and then immediately press TAB once. If the command ends with a slash after pressing TAB, press Enter and continue to the next paragraph.

This is the point where you need to remember what modifications you were going to make to the code. If you need to apply a patch to the code, first download (if necessary) the patch to a local file. Then run:

patch -p1 < [path to downloaded patch]

This command applies the patch in one go. You can repeat the patch command for each patch file you need to apply.

Build it!

You're not quite done, but you're getting close. Build the source code into an executable form by running this command:

debuild -us -uc -b

Depending on the size of the application, this may take seconds or it may take minutes. Some applications (Web browsers and office suites especially) can take hours to build, especially if your hardware isn't the latest.

Install this stuff

And now you should be able to see light at the end of the tunnel. List the files ending in .deb in the parent directory; these are the package archives that are the fruits of the building process above:

ls -l ../*.deb

That should produce a listing of one or more files. Install them using:

sudo apt-get install ../*.deb

NOTE: Even if you think you patched only one package or application (for example caja), there may well be multiple package archives that were just built. On Debian-based operating systems, many applications are split into multiple packages so that a minimum of disk space can be used by Debian "mirror sites" -- the servers on the Internet from which you regularly download your software and updates. So for example, continuing the example of caja, you may wind up with package files for caja, caja-common, libcaja-extension, and so on; while caja is the application itself, caja-common contains essential data files for the application. Though it may often look like you can get away with installing just the application's main package itself, sometimes the application's data files also are patched and/or changed, and the program will not work correctly unless you install all the produced package files!

Try it out!

Now it's time to take the software out for a test run. Usually, the program in question will not show the changes automatically; you'll have to close down the application and reload it (in the case of the MATE Panel, it's usually easiest to just log out and log back in).

When the application loads back up, you should see your modifications!

Optional (but recommended): Delete the BUILD directory

Now that you've successfully built the package (I hope -- right?), you don't need the temporary directory created above anymore, so delete it:

cd ../..
rm -r BUILD

And that's all there is to it! I hope I made this guide clear enough. Suggestions are welcome!


Hello gordon

Laziness - is one of the forces that motivates us to search for the most effort-optimised solution i.e. the most efficient solution. :slightly_smiling_face: