Despite that, it is possible to introduce new features to dwm by patching its source code, as dwm is source-based. Just to do basic configurations, we need to modify config.h, which is a part of dwm’s source code. While that may seem complex at first, patching dwm is simple once we understand a few things about the process. This article aims to teach the necessary skill set to successfully patch your own dwm installation and provide five useful patches.
What Are Patches?
Patches are small fragments of code that can be inserted in a bigger body of work. This is useful when collaborating on a big software project, as it allows programmers to quickly see changes made by others. Patches can be as simple as a small one-liner change to fix a bug or a massive multi-file change that introduces a new feature.
How to Patch a Source Code for dwm
There are multiple ways to introduce patches to a source code. The most common way of doing it is through a git command. For example, to introduce a patch in a git repository, type the following:
The apply function will attempt to insert the contents of the patch files in the source files that are indicated.The -3 option will attempt to fix any inconsistencies and allow the user to fix any mistakes in the patching process.
On the other hand, if we are editing the source code without any version control, we can use the GNU patch program. To insert a patch using that, type the following:
The -p1 option makes sure that the patch file will be correctly labeled for the patch program to insert.
However, when patching dwm, there are times these programs will fail, as they assume the source code we are patching is similar to the basic dwm installation. This means that as we install patches, the harder it will be for the patching program to insert those patches. Because of this, it is important to understand how the patch file works so that we could manually install the patches ourselves.
How to Read a Patch File
A patch file consists of three things:
Header that shows which file the code should be inserted inSubheading that shows which line number or function to insertThe code itself
As we have discussed above, a single patch file can contain multiple snippets of code intended to go to multiple files. This format allows us to distribute a single file rather than having a single patch file for every source file. With that, reading the patch file only requires us to understand the syntax of its headers. Once we know that, the actual patching is just a matter of copying and pasting the code.
The Patch Header Syntax
The header of a patch contains vital information regarding where the source file is located. For example, this is a header for the dwm autoresize patch. The first, third and fourth lines indicate that this is a diff between two versions of the dwm.c file. It tells us that the file that we are going to modify is the “dwm.c” file. However, just knowing what to edit would not help us in patching the source file. We still need to know where in the file we need to insert the code. This is where we can use the patch file’s subheadings. For example, this is a segment of the same autoresize patch described above: This might look like a daunting piece of code, but we only need to look at three things here:
The first line indicates the line number where we need to insert a snippet of code. In this example, we need to insert this on line 92.The second argument on the first line – struct Client { – tells the specific function that we have to edit. This is useful when the source file was already heavily patched and the line numbers on the left do not line up anymore.The last thing to look at is the + and - signs in the code block. The minus sign indicates that it is a line to be removed, and the plus sign indicates that it is a line to be added.
With that, we now have a basic understanding of how to patch source files. We can now proceed to discuss the five useful patches for dwm.
1. Systray
Unlike most desktop environments, dwm does not come with a system tray by default. The system tray is a segment of a desktop where some applications can leave an icon with the app’s functions to quickly interact with a program that is running in the background. This patch introduces that feature to dwm. Once installed, the systray patch will allocate the rightmost corner of the dwm bar to the current system tray programs. It also supports multi-monitor setups where the tray would always appear on the monitor that currently has the mouse pointer.
2. Xresources
The Xresources patch enables the xrdb program to set the graphical settings for dwm. It allows us to use the .Xresources file to change the colors and fonts without recompiling the program. It is especially useful for users that already use that same file for their terminal color scheme. Further, having xrdb dictate the appearance of dwm also allows us to use multiple themes. We can do that by modifying the .Xresources file for the color scheme that we want and enabling it by reloading dwm.
3. Tatami
Tatami is an alternative window layout for dwm. It represents the windows in the screen as tiles that are arranged in a traditional Japanese flooring. This approach is different than the traditional master and stack layout, where each window other than the master gets vertically thinner, therefore making each window in the stack unreadable. The tatami layout is particularly useful when dealing with four to five windows simultaneously, as it gives each window an ample screen space for the user to us for reading.
4. Focus Master
The way dwm arranges the windows is similar to placing blocks in a stack. Each new created window is placed on top of the previous window. This creates a linear order between the windows and allows us to know which window came first. However, one limitation of this design is that it doesn’t allow us to freely select the master window from the stack. In order to select the master, we need to select each and every window until we reach the highest block. This patch changes this behavior and allows us to select the current master window from anywhere in the stack. It is particularly useful when dealing with multiple windows, as it allows us to automatically select the master in the window stack rather than cycling to each window present.
5. dwmc
Modifying any aspect of dwm requires us to recompile the program whenever we want to apply our changes. This includes, among others, the color scheme and the default behavior. dwmc is a simple patch that allows us to change dwm’s behavior through a client program. This approach is similar to the way bspwm uses bspc to modify bspwm’s settings. While dwmc is far simpler than bspc, it still has a number of useful settings we can use and modify. For example, one function we can use in dwmc is togglebar. Running dwmc togglebar allows us to dynamically enable and disable the dwm bar. This makes dwmc useful when creating scripts that perform custom window behavior. Congratulations! You now have a basic understanding of how code patching works as well as five useful patches that you apply in your dwm installation. If you are looking for a similar minimal experience in a browser, check out this tutorial.
1. Are dwm patches safe to use?
Yes! A number of maintainers check the patches that are present in the suckless website. This ensures that all of the patches in the website work for the version of dwm it is written for.
2. I am using git apply, but my patch failed, and dwm is not compiling. What should I do?
This can happen due to a number of things. The most common reason is that the git headers were not removed in the source file. This is relatively easy to fix. We need to remove the headers and apply the patch manually ourselves. When you open the source file, you will see a line labelled HEAD. This indicates the start of the modification. It is followed by the function that needs to be modified. You will need to remove that line and perform the patching manually. In here, there will also be + and - signs on the left side of the code to guide you on what to change.
3. What do I do when I applied a patch successfully, but dwm doesn’t want to compile and is asking for missing variables or declarations?
The patching program didn’t patch the config.h file. By default, patches will edit the config.def.h file to avoid any conflicts with the current configuration. However, it means the config.h file will not load with the right configuration values for that particular patch. To fix this, you need to introduce the changes in the config.def.h file to your config.h file.
