Patching

This wiki article explains how to patch the source code of a package. Such patching enables you to do the following:

fix compiler errors
add debug output to understand bugs
fix bugs in the software
develop new features

Finding the aport

First of all, you need to find the aport of the package. The aport is the package build recipe, consisting at least of one APKBUILD file. In postmarketOS, these can be found in ~/.local/var/pmbootstrap/cache_git/pmaports. If you found it there already, you can continue with the next section.

postmarketOS is building on Alpine Linux, which means if you can't find a certain package in our pmaports folder, you need to grab the aport from Alpine. They store their aports in a git repository as well. You can either manually download one file after another for your aport from a git frontend such as GitLab or let pmbootstrap clone the repo and copy a package in pmaports' temp directory (e.g. ~/.local/var/pmbootstrap/cache_git/pmaports/temp): pmbootstrap aportgen --fork-alpine <package>

Alternatively, you can achieve this manually by cloning the entire git repository to your harddrive (see listing below). Make sure you put the original aport from Alpine into the temp folder of the postmarketOS aports.

For example, to clone Busybox:

$ git clone "https://gitlab.alpinelinux.org/alpine/aports.git"
$ cd aports
$ cp -r main/busybox ~/.local/var/pmbootstrap/cache_git/pmaports/temp
(adjust the pmbootstrap path as necessary)

Using "build --src"

Let's quickly take a look at the aport's APKBUILD. If it has a builddir= line inside it, you can use pmbootstrap's build --src feature, in that case read on here. Otherwise, see the legacy guide below.

Get the package's source code

With this approach, we extract the package's source code somewhere on your disk (so you can easily modify it outside of the chroots). To directly use the source tarball, which pmbootstrap also uses to build the aport, do the following:

start building the package: pmbootstrap build hello-world
open a second terminal with pmbootstrap log
in that terminal, you will see that it starts downloading the source package. mind the file name displayed there, and wait until the source has been downloaded.
then abort the build with ^C (or let it run through once to make sure this works, if the aport was not from pmOS but from Alpine - the compiler output will be cached, so it will be faster next time)

Now extract the source in your desired location:

$ mkdir -p ~/code/hello-world
$ cd ~/code/hello-world
$ tar -xvf ~/.local/var/pmbootstrap/cache_distfiles/source-1234.tar.gz

Initialize a git repository in that folder, so we can generate patch files from what you have changed in the source later:

$ git init .
Initialized empty Git repository in /home/user/code/hello-world/.git/
$ git add -A
$ git commit -m "initial"

As alternative to extracting the tarball, you can also directly clone the upstream's git URL.

Apply the aport's existing patches

If the aport already has patches, which may be necessary to compile the package with musl, you can add them to your checked out source as follows:

$ patch -p1 < ~/.local/var/pmbootstrap/cache_git/pmaports/main/yourpackage/first.patch
$ patch -p1 < ~/.local/var/pmbootstrap/cache_git/pmaports/main/yourpackage/second.patch
$ git add -A
$ git commit -m "applied the aports patches"

Building

Now build the package once without modifying anything else, just to make sure that it works:

$ pmbootstrap build hello-world --src=~/code/hello-world

As usually, the compiled packages can be found in ~/.local/var/pmbootstrap/packages. You can copy the resulting apk file to your device via SCP and install it on the target device with apk add -u if you like to.

Making changes

Change the source code now, and commit your change:

$ git add -A
$ git status
$ git commit -m "trying to fix the bug"

Then you can compile and test again.

Create a patch file

With git you can create the patch now. Some examples:

$ git diff HEAD~1 > mypatch.patch
Puts the last commit into a patch file.
$ git diff HEAD~2 > mypatch.patch
Puts the last two commits into a patch file.
$ git diff HEAD~1 HEAD~2 > mypatch.patch
Puts the commit before the last one into a patch file
$ git diff ffffff > mypatch.patch
Put everything that changed after commit ffffff into the patch file. You can
get the commit hashes easily by looking at "git log". Using the long commit
hashes also works.

Legacy Guide

This guide was written with the following use case in mind: you want to package an Android kernel. But it does not compile with our GCC6, so you need to patch the kernel. Unlike in the Android world, we do not fork the kernel repository and apply our patches there. Instead we ship our custom patches with the package build recipe in the aport folder.

This guide assumes, that you already know what to patch - if you don't know what to patch and only have the error, try to search the web for that error message. More often than not, there is a patch already available, that will fix it. If you don't have any luck, ask in the chat.

As everywhere else in the wiki, please expand this guide wherever information is missing that would have helped you!

Workflow

Try to compile your program with pmbootstrap build my-package. Note in which chroot it will actually build, it is the start of the building message. When it starts with (native) for example, the chroot is the "native" chroot (which is the default).
Wait until it fails or runs through (it works in both cases)
The sources of the kernel are now extracted in /home/pmos/build/src in the chroot where it was building.
Use pmbootstrap chroot to enter the chroot and to create the patch. It will enter the native chroot by default, if you need another chroot, then look at pmbootstrap chroot --help. Then do the following inside the chroot shell:
1. Install git and an editor such as nano with: apk add git nano
2. Switch from root to the user that we use for building: su - pmos
3. Go into the source folder: cd ~/build/src/
4. Patches get applied in the builddir, so usually there is another folder inside src, that you need to enter. You can check with ls which folders/files are inside the src folder. Enter that subfolder if necessary.
5. We'll be using git to create a patch file, so we will initialize a new repository and add everything:
  1. git init . (it will say: "Initialized empty Git repository in /home/pmos/build/src/.git/")
  2. git add -A
  3. git commit -m "initial"
6. Now it's time to edit the file you want to edit.
  1. export TERM=xterm
  2. nano Makefile (or whichever file you want to edit)
  3. NOTE: nano is glitchy when used like that. If it is unusable for you, run chmod 777 Makefile and then edit the file from outside the chroot with your favorite editor (a graphical one works, too!). The path is similar to: ~/.local/var/pmbootstrap/chroot_native/home/pmos/build/src/(optional builddir)/Makefile.
7. (You need to still be in the chroot!) run git diff to get a patch file generated to the screen. You can save it to a file by redirecting it: git diff > /tmp/mypatch.patch.
8. Quit the chroot by pressing ^D (CTRL+D) twice (typing exit also works).
Copy the patch file you have created to your aport folder (adjust the work path, that you have given pmbootstrap init and the chroot suffix native if necessary):
1. cp ~/.local/var/pmbootstrap/chroot_native/tmp/mypatch.patch ~/code/pmbootstrap/aports/device/linux-my-cool-kernel/mypatch.patch
Rename the mypatch.patch file to give it a meaningful name!
You can add arbitrary text at the top of the patch file. Use this to paste the error message that you got during compilation there, with a note that this will be fixed by this patch.