└── README.md /README.md: -------------------------------------------------------------------------------- 1 | suckless-101 2 | ============ 3 | 4 | Guide on how to patch, compile and install suckless software. 5 | 6 | Table of contents: 7 | 8 | * [Introduction](#introduction) 9 | * [Toolchain](#toolchain) 10 | * [Manual pages](#manual-pages) 11 | * [Getting the source](#getting-the-source) 12 | * [Dependencies](#dependencies) 13 | * [Compiling](#compiling) 14 | * [Installation](#Installation) 15 | * [Patching](#patching) 16 | * [Customization](#customization) 17 | 18 | ## Introduction 19 | 20 | The guide explains how to patch, compile and install suckless software. 21 | 22 | `dwm` is used for examples. 23 | 24 | ## Toolchain 25 | 26 | To successfully compile program source code you'll need a C 27 | compiler and several other tools installed on your system: 28 | 29 | * C compiler `gcc`, (`clang` or `tcc` should work as well) 30 | * `git` 31 | * `make` 32 | * `pkg-config` 33 | * `patch` 34 | 35 | Some distributions provide a package that includes most of the desired 36 | tools: 37 | 38 | * `base-devel` in Void Linux, Arch Linux 39 | * `build-essential` in Debian, Ubuntu 40 | 41 | You may find similar packages for other Linux distributions by 42 | searching for _"build-essential equivalent [DISTRO NAME]"_. 43 | 44 | After you've installed required tools ensure all of them present: 45 | 46 | $ which gcc git make pkg-config patch 47 | /usr/bin/gcc 48 | /usr/bin/git 49 | /usr/bin/make 50 | /usr/local/bin/pkg-config 51 | /usr/bin/patch 52 | 53 | ## Manual pages 54 | 55 | To get documentation for installed programs use `man`: 56 | 57 | $ man patch 58 | 59 | Most manual pages you will read with `man` will include a program 60 | description and comprehensive guide on command line parameters and 61 | configuration options. 62 | 63 | An important plus of reading man pages locally is that the manual page 64 | will provide documentation of the actual program you have installed and 65 | not some other older/newer version of it. 66 | 67 | ## Getting the source 68 | 69 | After installing required tools you may continue with cloning the 70 | program source code. 71 | 72 | To get the source code of `dwm` use `git`: 73 | 74 | $ git clone https://git.suckless.org/dwm 75 | 76 | You may find source code for other programs by browsing suckless git 77 | repositories: 78 | 79 | https://git.suckless.org/ 80 | 81 | ## Dependencies 82 | 83 | To compile program you'll need to install runtime and build dependencies. 84 | 85 | To find required dependencies examine `config.mk` and `Makefile`. 86 | 87 | For example `dwm` dependencies on Void Linux are satisfied by the 88 | following packages: 89 | 90 | * libX11-devel 91 | * libXft-devel 92 | * libXinerama-devel 93 | 94 | **NOTE:** It is important to install development variants of packages 95 | to get C header files. These files are required to compile the source code. 96 | 97 | Another way to find dependencies would be to examine compile errors. 98 | Here error text says that `Xft.h` header file is missing: 99 | 100 | drw.c:6:10: fatal error: X11/Xft/Xft.h: No such file or directory 101 | 6 | #include 102 | | ^~~~~~~~~~~~~~~ 103 | 104 | Examine each error to find a name of a missing C header file and 105 | install the package which provides it. 106 | 107 | One way to quickly locate the desired package is by using a package 108 | manager or a separate utility to search packages by filenames they 109 | contain. 110 | 111 | For example on Void Linux such program can be installed with `xtools` 112 | package: 113 | 114 | $ xlocate Xft.h 115 | libXft-devel-2.3.3_1 /usr/include/X11/Xft/Xft.h 116 | 117 | ## Compiling 118 | 119 | To compile a program run `make` in its root directory: 120 | 121 | $ make 122 | 123 | In case of compilation errors: 124 | 125 | * check that required build tools present, 126 | * check missing dependencies. 127 | 128 | ## Installation 129 | 130 | Most suckless software will have a Makefile target to install built binaries, 131 | man files, etc. 132 | 133 | To install in home directory run 134 | 135 | $ make PREFIX=$HOME/.local/ install 136 | 137 | This way you won't need root rights and program files won't mess with system 138 | files. This is a prefered way to install built software. 139 | 140 | **NOTE:** You'll need to add `$HOME/.local/bin` to your PATH variable. 141 | 142 | --- 143 | 144 | To install system-wide run 145 | 146 | # make install 147 | 148 | > Here `#` in front of command meens a root shell. 149 | > Run such commands as root user (with `sudo` for example). 150 | 151 | 152 | ## Patching 153 | 154 | Patches are files that tell the differences between two files. With the 155 | difference, you can, for instance, include lines in a source code that create 156 | new functionality. 157 | 158 | There are lots of patches available for various suckless programs. You can find 159 | patches for `dwm` and others by browsing the website: 160 | 161 | https://tools.suckless.org/dwm/patches/ 162 | 163 | Download patch file with `curl`: 164 | 165 | $ curl -O https://dwm.suckless.org/patches/alpha/dwm-alpha-20201019-61bb8b2.diff 166 | 167 | Apply downloaded patch file with `patch` tool: 168 | 169 | $ patch -i dwm-alpha-20201019-61bb8b2.diff 170 | 171 | Don't forget to rebuild and install program after you've made changes to source 172 | code. 173 | 174 | Some patches will change `config.def.h` file. This file is copied by Makefile 175 | once to `config.h` file. Remove `config.h` and run `make` or run `make -B`. 176 | **Note:** any changes you've made in config.h will be lost. 177 | 178 | In case you feel you are totally messed something run 179 | 180 | $ git checkout . 181 | 182 | to undo changes made by patches (and you). 183 | 184 | Another way to manage patches is by using git branches. 185 | 186 | 187 | ## Customization 188 | 189 | Most suckless programs are customized by editing source code or `config.h` file: 190 | 191 | https://dwm.suckless.org/customisation/ 192 | 193 | Don't forget to rebuild and install program after you've made changes to source 194 | code. 195 | --------------------------------------------------------------------------------