Jump to content

Porting to a new device/Kernel package/Kernel compilation

From postmarketOS Wiki

Next up is the kernel compilation, which will fail a few times before you get it working. Run it once to see where it fails.

$ pmbootstrap build linux-wiki-example

We most likely use a more modern version of GCC compared to what your device kernel was intended to be compiled with (which is good, we don't want outdated software). However, this means that you will probably need to patch your kernel before it compiles successfully. Don't be scared, we'll talk you through it. But in the unlikely case that everything runs through smoothly, continue reading here.

Find the error message

Note Tip: you can use pmbootstrap log to check the log quickly.

To find the error message, you should open a log file in your favorite text editor, like

$ nano $(pmbootstrap config work)/log.txt

and use search to find error messages for the last build run (they contain error: or Error word).

Examples of errors:

In file included from arch/arm/mach-msm/perf_trace_counters.h:127:0,
                 from arch/arm/mach-msm/perf_trace_counters.c:14:
include/trace/define_trace.h:79:43: fatal error: ./perf_trace_counters.h: No such file or directory
drivers/built-in.o: In function `.LANCHOR1':
msm_iommu_sec.c:(.data+0x9298): undefined reference to `kgsl_iommu_sync_lock'
msm_iommu_sec.c:(.data+0x929c): undefined reference to `kgsl_iommu_sync_unlock'
Makefile:877: recipe for target '.tmp_vmlinux1' failed
make: *** [.tmp_vmlinux1] Error 1

It is possible to clear the log file right before compilation when you press ctrl + c in the log window and use log -c:

(old log output here)
^C
$ pmbootstrap log -c

Another trick to find the error message real quick is to open log.txt with less and use the follow mode (press F while in less or open less with the +F option: less +F log.txt). This causes less to behave like tail -f. When an error occurs, you can exit the follow mode by pressing ctrl + c and use ? to reverse search the output (for example: ?error). Press F to re-enable follow mode.

Get a patch

From postmarketOS aports

It is highly likely that we already ran into the same issue with another kernel. Take (parts of) the offending file name and search for it inside pmaports/device.

$ grep -r 'perf_trace_counters\.c' pmaports/device/
pmaports/device/testing/linux-lg-mako/01_msm-fix-perf_trace_counters.patch:In-tree compilation for arch/arm/mach-msm/perf_trace_counters.c was
pmaports/device/testing/linux-lg-mako/01_msm-fix-perf_trace_counters.patch:                     from arch/arm/mach-msm/perf_trace_counters.c:14
$ grep -r 'msm_iommu_sec' pmaports/device/
pmaports/device/testing/linux-lg-mako/02_gpu-msm-fix-gcc5-compile.patch:msm_iommu_sec.c:(.data+0x9298): undefined reference to `kgsl_iommu_sync_lock'
pmaports/device/testing/linux-lg-mako/02_gpu-msm-fix-gcc5-compile.patch:msm_iommu_sec.c:(.data+0x929c): undefined reference to `kgsl_iommu_sync_unlock'

When there is a result, copy the patch file you found to your new kernel package, add it to the source variable in the APKBUILD and try building again.

$ cp pmaports/device/testing/linux-lg-mako/01_msm-fix-perf_trace_counters.patch pmaports/device/testing/linux-wiki-example/
$ nano pmaports/device/testing/linux-wiki-example/APKBUILD # add it to source
$ pmbootstrap checksum linux-wiki-example
$ pmbootstrap build linux-wiki-example

From elsewhere

Fire up your favorite search engine and look at all results for the error message and variations of it. The "" feature of most search engines is useful, so it searches for an exact string and not single words. Example queries for the error messages above:

  • include/trace/define_trace.h: fatal error: ./perf_trace_counters.h: "No such file or directory"
  • linux "./perf_trace_counters.h: No such file or directory"
  • android "undefined reference to `kgsl_iommu_sync_unlock'"

In most cases, this will yield a patch that you can apply to your kernel. Save what you have found as a patch file right next to the APKBUILD of your new kernel package. Mailing list posts are usually in the format of a patch file and can be used directly, while commits or pull requests (PRs) on GitHub can be downloaded as patch when you append .patch to the URL (e.g. commit, patch).

If what you found on the web can't be used as patch file directly (e.g. sometimes the files are in other folders), but you understood how you would need to patch the source (from the search results or simply because you already knew), please follow this guide.

Patch files can contain arbitrary text before the first line with --- in the file. Please use this space to link to the source where you found a patch (in case it is from the Internet) and to paste the error message, that your patch fixes (so it is easier to find for other people).

After creating the patch file and adding the source URL and error message, put the file name into source in your APKBUILD and give it another shot.

$ nano pmaports/device/testing/linux-wiki-example/03_description-here.patch
$ nano pmaports/device/testing/linux-wiki-example/APKBUILD
$ pmbootstrap checksum linux-wiki-example
$ pmbootstrap build linux-wiki-example

We can't promise anything, but you shouldn't need to do this more than 2 times or so before the kernel build finally goes through.

Removing python2 dependency

In some downstream kernels, weird python scripts are running as part of the build process. This is especially problematic for python2 scripts, as python2 has been removed in Alpine 3.16 (postmarketOS v22.06). So if your kernel build fails with an error message mentioning that "python2" was not found, here are some tips to get rid of the dependency:

  • If the python2 program is mediatek's drvgen: this is for generating a "cust.dtsi" file. Just include the the "cust.dtsi" file it would generate and don't call drvgen during the build. You can obtain the file by checking out the v21.12 branch of pmaports.git, adding your kernel package there, adding python2 to makedepends temporarily in the APKBUILD and starting the build. Once it got past the part where it would stop with the python2 error, the cust.dtsi file should be available. Create a patch that adds it and disables drvgen, search pmaports.git master for drvgen to find similar patches.
  • If the python2 program is mkdtimg (or mkdtboimg), you should be able to use the python3 version -add it to makedepends- we have packaged in android-tools "android-mkdtboimg previously" instead. Use "git grep" to find similar patches, e.g. device/unmaintained/linux-xiaomi-cepheus-downstream/0005-Use-real-mkdtimg-don-t-use-python2-one.patch.

Changing compiler

Using GCC6

If you can't make your kernel compile or boot with the latest GCC from Alpine, you can also try to use GCC6 instead.

Using GCC4

As GCC4 was recently introduced in postmarketOS repos, you can follow the procedure for GCC6 above and replace all gcc6 occurrences with gcc4 and add gcc4 gcc4-(armv7/armhf/...) to your list of dependencies.

Using Clang

To use Clang as compiler you have to do the following in kernel package's APKBUILD:

  • Add clang to makedepends
  • Add these lines:
export CC="clang"
export HOSTCC="clang"

Example

If older version of Clang is needed, check if it is available in Alpine Linux package repositories: https://pkgs.alpinelinux.org/packages?name=clang%3F%3F&branch=edge&arch=

E.g. to use clang20, add it to makedepends and set CC and HOSTCC:

export CC="clang-20"
export HOSTCC="clang-20"