Compiling kernels with envkernel.sh

This page details how to compile a kernel manually using the  helper script as well as how to package and install a locally compiled kernel. This workflow can be used to quickly iterate and test during kernel development by using the existing kernel packaging and upgrade process to install a development kernel.

Usually when compiling a kernel, you would install all dependencies and a cross compiler in your host system. To make it easier, we have the  script (for fish shell:  ). It sets up an Alpine Linux chroot with all the dependencies by using  internally, exports the environment variables to use the right cross compiler and creates an alias to. This means, whenever you type  after sourcing that script, it will actually run   in the chroot.

Selecting a kernel
This section details how to fetch the kernel source of an existing postmarketOS device. Existing kernel aports can be found in the  directory.

In the following example we will use the  device. The kernel aport is in the directory. Within the APKBUILD is the  variable which lists the kernel source repository.

After determining the kernel you want to work with, download the source code.

Preparing the source directory
To compile the current version of the kernel, check out the git revision found in the APKBUILD.

Applying patches
Some kernel aports have patches applied on top of the remote source. You may want to apply these patches if they aren't in the source tree you have checked out.

For example  has a patch which isn't in the git revision in the prior example.

Kernels which can only be compiled with older GCC versions may need the. If this header exists in the kernel aport then copy it to the kernel source directory.

Compile the kernel
The  script will set up a build environment based on the target device configured for.

In this example we are using the  device. So we should be sure to have run  and select   as the target device. Most devices should include a link to their kernel package at the bottom of their wiki page.

Run the  script once in the kernel source directory to initialize the build environment. If the kernel can only be compiled with GCC6 then pass the  flag.

Copy the defconfig from the kernel aport to the kernel source directory.

Build the defconfig and kernel with the following commands.

Post make scripts
Some kernels require extra packaging steps such as. The  build environment works within the pmbootstrap chroots. The  alias can be used to execute scripts within the source or build directory in the chroot.

In this example we are using the  which requires. Create a script with the  command named   in the kernel source directory.

Run the script.

Packaging and flashing the kernel
A kernel compiled under  can be packaged by pmbootstrap by using the   build option.

Usually if the device boots to SSH with USB networking and has support for kernel upgrades, you can install the new kernel by sideloading.

After compiling and packaging the kernel, it can be flashed to device using the standard pmbootstrap flash commands. Note that if your kernel includes kernel modules (most mainline kernels do) these will not be installed and some features might break when you boot back up. In this case you can sideload as above once you have a booting kernel.

Packaging kernels built without envkernel
As of (not yet merged as of 2022-09-13) the envkernel packaging logic can be used to package kernels built directly on the host. This is intended to allow folks who prefer to set up their own kernel building environment to still make use of pmbootstrap for packaging and sideloading the new kernel.

Currently this requires that you use  as your output directory (add   as an argument to make). With that done just build your kernel as normal and follow the packaging/flashing steps above.