|
| 1 | +# :material-layers-plus: Patches and Overlays |
| 2 | + |
| 3 | +!!! danger "Important: Read this before you start!" |
| 4 | + |
| 5 | + This section deals with adding **patches** to your KNULLI installation **manually**. This is **not** a guide for **regular updates**. Please be absolutely aware that this guide is just a kick-off guide for **advanced users** who want to learn more about Linux and apply manual changes to their KNULLI installation. |
| 6 | + |
| 7 | + If you are looking for information on how to update your KNULLI device regularly, please head to the [Update](../../play/update) section instead! |
| 8 | + |
| 9 | +!!! warning "SSH network access to your device is mandatory" |
| 10 | + |
| 11 | + Before reading any further, be aware that it is **mandatory** to be able to access a command line on your KNULLI device via **SSH** to **install patches** and **create overlays**. Consequently, you will **not** be able to do either unless your device is connected to your Wi-Fi (as explained in the [Networking](../networking) section) and you have prepared SSH access to your device (as explained in the [SSH](../ssh) section). |
| 12 | + |
| 13 | +This section covers details about installing **patches** and persisting changes to the operating system in an **overlay**. As a **regular KNULLI user**, you probably do **not** need to know any of this. This entire section is written for two groups of users: |
| 14 | + |
| 15 | +* **Community members** from our [:simple-discord: Discord](https://discord.gg/HXPS3DAeeB) who want to try patches **before** they are included in a new internal or public build. |
| 16 | +* **Advanced users** who know their way around Linux and want to make changes to their KNULLI setup. |
| 17 | + |
| 18 | +## Understanding Linux file systems |
| 19 | + |
| 20 | +If you are a Windows user who has never worked with Linux before, you might want to take a little time to understand how Linux file systems work. Bare in mind that this is a **simplified** explanation which is only meant to pick you up and give you a brief understanding of how KNULLI works differently from your Windows PC. If you want to learn more about how Linux work, we **strongly** recommend to find a more extensive source of information. |
| 21 | + |
| 22 | +### File systems on Windows machines |
| 23 | + |
| 24 | +On your Windows computer, each **drive** (or **partition**) has an assigned **drive letter**. You might think about them like labeled drawers of a filing cabinet. The **main drive** that hosts your Windows installation traditionally uses the drive letter `C:` - this is a relic of a time when drive letters `A:` and `B:` where reserved for the two floppy disc drives computers used to have. However, if you connect another drive to your PC, like a thumb drive or a SD card, Windows automatically assigns new drive letters to them, so you can access those drives from your *Windows Explorer*. Files and folders are addressed by their **absolute path** which starts with the **drive letter**. E.g., the folder which holds your pictures is located at |
| 25 | + |
| 26 | +``` |
| 27 | +C:\Users\<username>\Pictures |
| 28 | +``` |
| 29 | + |
| 30 | +### File systems on Linux machines |
| 31 | + |
| 32 | +Linux filesystems work a little different. On Linux, every **drive** is treated like a **folder**. A Linux system always has a so called **root** that **loosely** corresponds conceptually to the drive letter `C:` on a Windows machine. The **root** is always referred to by the symbol `/`. By definition, each **absolute path** always starts with `/` symbol. |
| 33 | + |
| 34 | +Other **drives** are treated like **subfolders** of the **root**. With a command called `mount`, any **empty folder** on a Linux system can be assigned to **any drive** of the device. It is even allowed, to have **more than one folder** that points to **the same drive**. Following the previous metaphor, consider a filing cabinet with only a **single drawer**. |
| 35 | + |
| 36 | +For example, on your KNULLI device, your games are stored in |
| 37 | + |
| 38 | +``` |
| 39 | +/userdata/roms |
| 40 | +``` |
| 41 | + |
| 42 | +### The KNULLI file system |
| 43 | + |
| 44 | +KNULLI is a Linux, so it uses a Linux file system. The entire KNULLI system is stored in a **read-only** SquashFS. (You can learn more about SquashFS on [Wikipedia](https://en.wikipedia.org/wiki/SquashFS).) The **only exception** is a **writable** folder called `/userdata`. |
| 45 | + |
| 46 | +During boot, KNULLI uses the `mount` command to make the folder `/userdata` point to a **writable** drive. By switching between **internal** and **external** storage (as explained in the [Second SD Card](../../play/add-games/second-sd-card) section), you tell KNULLI which **drive** to mount as `/userdata` during boot: |
| 47 | + |
| 48 | +* If you use a **single SD card** setup (**internal** storage), KNULLI mounts the `SHARE` partition of **SD 1**. |
| 49 | +* If you use a **dual SD card** setup (**external** storage), KNULLI mounts the main partition of **SD 2**. |
| 50 | + |
| 51 | +When accessing your KNULLI device via Windows/SMB network transfer (as explained in the [Network Transfer](../../play/add-games/network-transfer) section), you will access a network drive called `share` that corresponds **exactly** to your **current** `/userdata` folder. The SMB address |
| 52 | + |
| 53 | +``` |
| 54 | +\\KNULLI\share |
| 55 | +``` |
| 56 | + |
| 57 | +points to the exact same place as the absolute path |
| 58 | + |
| 59 | +``` |
| 60 | +/userdata |
| 61 | +``` |
| 62 | + |
| 63 | +on your KNULLI device. |
| 64 | + |
| 65 | +The [Game Storage](../../play/add-games/game-storage) section covers in great detail how to use the **writable** part of your device to add games, BIOS files, bezel decorations, etc. However, when you want to install **patches**, you want to modify files **outside** of the writable `/userdata` folder - that is, where the **overlay** comes into play. |
| 66 | + |
| 67 | +#### Many ways lead to Rome |
| 68 | + |
| 69 | +Keep in mind that Linux allows multiple paths to the same files and folders: |
| 70 | + |
| 71 | +``` |
| 72 | +/media/SHARE |
| 73 | +``` |
| 74 | + |
| 75 | +points to your **internal** storage while |
| 76 | + |
| 77 | +``` |
| 78 | +/media/SHARE_1 |
| 79 | +``` |
| 80 | + |
| 81 | +points to your **external** storage (if you have a dual SD card setup). |
| 82 | + |
| 83 | +Consequently, on a **single SD card setup**, the paths |
| 84 | + |
| 85 | +``` |
| 86 | +/media/SHARE/system/batocera.conf |
| 87 | +``` |
| 88 | + |
| 89 | +and |
| 90 | + |
| 91 | +``` |
| 92 | +/userdata/system/batocera.conf |
| 93 | +``` |
| 94 | + |
| 95 | +point **to the exact same file**. |
| 96 | + |
| 97 | +Following that principle, on a **dual SD card setup**, the paths |
| 98 | + |
| 99 | +``` |
| 100 | +/media/SHARE_1/system/batocera.conf |
| 101 | +``` |
| 102 | + |
| 103 | +and |
| 104 | + |
| 105 | +``` |
| 106 | +/userdata/system/batocera.conf |
| 107 | +``` |
| 108 | + |
| 109 | +point **to the exact same file**, too. |
| 110 | + |
| 111 | +## The overlay |
| 112 | + |
| 113 | +Since everything outside of the `/userdata` folder of your KNULLI installation is **read-only** by definition, you will need to create an **overlay** to make **permanent** changes to your KNULLI installation. Otherwise, all changes will simply be undone after every reboot of your system. |
| 114 | + |
| 115 | +Your primary SD card (SD1) has a drive called `BATOCERA`, which is formatted to **FAT32** and can be accessed easily from Windows, Linux, and MacOS. On that drive, you will find a folder called `boot` which contains a **file** called `batocera` - that file contains the **majority of your KNULLI installation**. (This is why you can manually update your KNULLI installation by simply replacing this file, as explained in the [Update](../../play/update) section. |
| 116 | + |
| 117 | +The **overlay** is **another** file that is just called `overlay` and resides in the same folder. The overlay is **optional** - usually, users do **not** have an overlay in place. The **overlay file** contains **changes** you made to the KNULLI installation, which will be applied **during boot**. |
| 118 | + |
| 119 | +!!! danger "Important: Undo changes" |
| 120 | + |
| 121 | + If you have created an overlay that breaks your system, you can always **undo** all your changes by simply **deleting** the **`overlay` file** from the `boot` folder of your `batocera` partition. |
| 122 | + |
| 123 | + We **strongly recommend** to **always remove** your current overlay when you **update** your KNULLI installation, because patches and other modifications stored in the overlay might be **in conflict** with the new KNULLI version. |
| 124 | + |
| 125 | +## Installing patches (or manual modifications) |
| 126 | + |
| 127 | +!!! warning "Patches" |
| 128 | + |
| 129 | + Some community members on our [:simple-discord: Discord](https://discord.gg/HXPS3DAeeB) server occasionally provide patches you can install **manually**. These patches are usually new features which are either **considered** or already **confirmed** to be included in a future KNULLI release. Be aware that patches might be **experimental** and sometimes just a **prototype** for a final solution! |
| 130 | + |
| 131 | + By installing a patch and reporting feedback to the developers, you provide valuable assistance to the development of KNULLI. However, patches are often not yet approved by the community or the lead developers of the KNULLI project, consequently, there are no guarantees that they will work for **you**. |
| 132 | + |
| 133 | + Before installing a patch, make sure you find the source **trustworthy**. |
| 134 | + |
| 135 | +Most patch installations (or manual modifications) to your KNULLI system follow a simple pattern: |
| 136 | + |
| 137 | +* Add, replace, or remove files **outside** of your `/userdata` folder |
| 138 | +* Make some of the files **executable** by applying the command `chmod +x` to the files. |
| 139 | +* **Create** or **update** your **overlay** by executing the command `batocera-save-overlay` which makes all the changes persistent. |
| 140 | +* Reboot your device. |
| 141 | + |
| 142 | +Some developers **simplify** this process for you, by providing a **patch installer** which does most of these steps for you. However, even if you received a patch installer, you will still have to make the patch installer **executable** and run it from an SSH command line. |
| 143 | + |
| 144 | +### Putting files into the right places |
| 145 | + |
| 146 | +There are several options to put files in the right places **outside** of the `/userdata` folder. |
| 147 | + |
| 148 | +* Some patches come with a **patch installer** which moves the file for you. In this case, simply store the **patch installer** and all patch files in your `/userdata` folder according to the specifications made by the developer. |
| 149 | +* You can use SCP/FTP to access the entire KNULLI file system. You will find a subsection on how to use SCP/FTP in the [Network Transfer](../../play/add-games/network-transfer) section. This approach allows to put the files **directly** to their **final destination**. |
| 150 | +* You can copy the files to your `/userdata` folder by the same method you add your games and BIOSes. Afterwards, you can move the files **from** their location inside `/userdata` **to** their **final destination** |
| 151 | + * **either** by using the *OD-Commander* tool you will find in the *Ports* category of your KNULLI device |
| 152 | + * **or** by connecting via SSH (as explained in the [SSH](../ssh) section) and copying/moving the files via `cp`/`mv` on the command line, e.g., |
| 153 | + ``` |
| 154 | + cp /userdata/system/some-file.sh /usr/bin/some-file.sh |
| 155 | + ``` |
| 156 | + or |
| 157 | + ``` |
| 158 | + mv /userdata/system/some-file.sh /usr/bin/some-file.sh |
| 159 | + ``` |
| 160 | + |
| 161 | +### Making files executable |
| 162 | +
|
| 163 | +After you have moved the files in the right places, you need to make sure that all files which are **supposed** to be executable **actually are** executable. Again, you have several options to achieve this: |
| 164 | +
|
| 165 | +* If using WinSCP, you can right-click a file and select *Properties*. |
| 166 | + * In the *Common* tab, go to the *Permissions* section and make sure all the *X*es are **checked** if the file is required to be **executable**. |
| 167 | +* If connected via SSH (as explained in the [SSH](../ssh) section), you can |
| 168 | + * use the `ls` command to check the permissions of a file, e.g., |
| 169 | + ``` |
| 170 | + ls -l /userdata/system/patch-installer.sh |
| 171 | + ``` |
| 172 | + to see if a file called `patch-installer.sh` is executable. The response will look like |
| 173 | + ``` |
| 174 | + -rwxr-xr-x 1 root root 458 Aug 3 22:20 /userdata/system/patch-installer.sh |
| 175 | + ``` |
| 176 | + and you can tell from the part `rwxr-xr-x` if a file is executable (you see 3 `x` letters) or not (you see less than 3 or even no `x` letters). |
| 177 | + * use the `chmod` command to change the permissions of a file and make it executable, e.g., |
| 178 | + ``` |
| 179 | + chmod +x /userdata/system/patch-installer.sh |
| 180 | + ``` |
| 181 | +
|
| 182 | +### If provided: Run the patch installer |
| 183 | +
|
| 184 | +If your patch came with a **patch installer** which you have made executable in the previous step, you can now **execute** the patch installer from the SSH command line. To do so, establish a SSH connection (as explained in the [SSH](../ssh) section) and launch the installer by calling the script by its name from the command line (**Mind the dot** at the beginning of the command!), e.g., |
| 185 | +``` |
| 186 | +./userdata/system/patch-installer.sh |
| 187 | +``` |
| 188 | +
|
| 189 | +Have a close look at the output of this command, maybe copy-paste it to a text file for debugging purposes and reach out to the [:simple-discord: Discord](https://discord.gg/HXPS3DAeeB) community if you have problems understanding the output. |
| 190 | +
|
| 191 | +### If required: Create overlay manually |
| 192 | +
|
| 193 | +Some **patch installers** implicitly create or update the **overlay**. However, some do not. If your patch did **not** come with a patch installer, if you want to patch in your **own modifications**, or if you are not sure whether the patch you applied created an overlay, you better do it yourself. To do so, establish a SSH connection (as explained in the [SSH](../ssh) section) and execute the following command: |
| 194 | +``` |
| 195 | +batocera-save-overlay |
| 196 | +``` |
| 197 | +Once the overlay was created/updated successfully, you can type |
| 198 | +``` |
| 199 | +reboot |
| 200 | +``` |
| 201 | +to reboot your system and check if your changes are still in place afterwards. |
0 commit comments