Building a Custom System Image with pmbootstrap and Editing Kernel APKBUILD Settings

Building your own custom postmarketOS image with custom kernels and settings. Then flash it to the device or build an image.

In my postmarketOS installation article, I mentioned the method for creating images with pmbootstrap. In practice, this uses pmbootstrap to download each device’s configuration files from the official Gitlab repository, then builds everything by hand with scripts.

pmbootstrap also provides functionality for porting new devices. Users can add device models themselves and do porting work.

But today I want to talk about modifying existing device configuration files so you can change the build-time configuration. For example, compiling extra drivers into the Linux kernel or adding default packages. pmbootstrap init cannot do that for us, so we have to edit the APKBUILD file.

At the end, I also include the steps for installing the modified system and building a postmarketOS image file.

1. Find the Device Configuration Files

#

The APKBUILD file is a script that tells pmbootstrap how to handle the Linux kernel.

So where do you find the APKBUILD for the device you want?

When we run pmbootstrap init, pmbootstrap clones a copy of the Gitlab repository.

All device configuration files are located here: ~/.local/var/pmbootstrap/cache_git/pmaports/device/

Every postmarketOS device has corresponding directories beginning with linux- and device-.

The linux- directory contains Linux kernel build-related settings.

The directory beginning with device- contains the hardware information for that device.

For example, this is the case for pine64-pinetab2 (note: when this was written, the Pinetab2 APKBUILD had not yet entered the Gitlab repository. I manually cloned this from a pull request):

├── device-pine64-pinetab2
│   ├── APKBUILD
│   ├── deviceinfo
│   └── uboot-script.cmd
└── linux-pine64-pinetab2
    ├── APKBUILD
    └── config-pine64-pinetab2.aarch64

Since not every device can use a mainline kernel, each postmarketOS device has its own Linux kernel configuration files. In the postmarketOS design, the Linux kernel for most devices is an APK package called a “Downstream kernel specific package”, corresponding to the linux- directory mentioned above.

For devices already ported into the Gitlab repository, the kernel is usually also included in the postmarketOS edge branch package repository, so there is no need to compile it manually.

Correspondingly, the directory beginning with device- is called a “Device specific package”. This package contains the rest of the configuration files for the device.

Since we said we want to customize the build configuration, let’s actually change something. Every device has an APKBUILD file recording how it is built, and that is what we need to edit.

2. Modify the Kernel APKBUILD

#

1. First, finish running pmbootstrap and specify the build device as pine64-pinetab2.

2. Enter the directory ~/.local/var/pmbootstrap/cache_git/pmaports/device/linux-pine64-pinetab2.

3. You can see the APKBUILD file. Its contents are simple enough; anyone who has written bash should be able to understand it.

└── linux-pine64-pinetab2
    ├── APKBUILD
    └── config-pine64-pinetab2.aarch64

4. According to the official Wiki page for Downstream kernel specific package, you can add custom build commands to APKBUILD, specify a GCC version, and apply extra patches.

5. The first thing to care about is how the kernel source code is obtained. For PineTab2, it downloads a tar.gz file from the maintainer’s own repository and then hands it to pmbootstrap for compilation.

# Source
_tags="v6.6.4-danctnix2"
_config="config-$_flavor.$arch"
source="
	$pkgname-$_tags.tar.gz::https://github.com/dreemurrs-embedded/linux-pinetab2/archive/$_tags.tar.gz
	$_config
"
builddir="$srcdir/linux-pinetab2-${_tags:1}"
_outdir="out"

6. Every time the kernel source URL changes, you usually need to regenerate the hash. Run the command in the terminal and let pmbootstrap calculate the hash automatically and write it back into APKBUILD.

pmbootstrap checksum linux-pine64-pinetab2

7. After that, you can work with the kernel source. If you only want to enable a few kernel options, just enter kconfig:

pmbootstrap kconfig edit linux-pine64-pinetab2

8. The kernel options edited in kconfig will be saved to the file beginning with config- in the same directory.

9. Then try recompiling the kernel. pmbootstrap compiles the kernel through cross-compile inside an ARM chroot.

# Confirm that the kernel satisfies postmarketOS requirements
pmbootstrap kconfig check

# Add -j8 during compilation to speed it up
pmbootstrap build linux-pine64-pinetab2

10. If you want to compile with completely different kernel source code, prepare it yourself in another directory (things inside the chroot are not convenient to access), then use --src to tell pmbootstrap the kernel source path.

pmbootstrap build linux-pine64-pinetab2 --src=/home/user/Downloads/linux-pinetab2-kernel

3. Modify the Device APKBUILD

#

1. Enter the directory ~/.local/var/pmbootstrap/cache_git/pmaports/device/device-pine64-pinetab2, which contains the following:

├── device-pine64-pinetab2
│   ├── APKBUILD
│   ├── deviceinfo
│   └── uboot-script.cmd

2. deviceinfo is mainly hardware information for the device, while APKBUILD is the device configuration. For the contents, refer to the Wiki page for Device specific package.

3. For example, add instructions for installing extra packages to subpackages (separate multiple packages with spaces). This quotes the Wiki’s example: add a subpackage named $pkgname-x11, then add an x11() function instructing it to install the xf86-video-qxl package.

subpackages="
$pkgname-kernel-v0:kernel_v0
$pkgname-kernel-v2:kernel_v2
$pkgname-x11
"

x11() {
	install_if="$pkgname=$pkgver-r$pkgrel xorg-server"
	depends="xf86-video-qxl"
	mkdir "$subpkgdir"
}

4. Next, build the device package.

pmbootstrap build device-pine64-pinetab2

4. Build the Full System Image

#

Time to install the modified system onto the device.

For the steps to build postmarketOS, see creating images with pmbootstrap. Usually there are the following build methods:

1. Install to SD card
2. Flash with fastboot
3. Flash with a flashable package

The latter two methods are for former Android devices. My PineTab 2 is a development board that supports U-Boot, so writing the system to an SD card or eMMC is enough.

Insert the SD card into the PC, use lsblk to confirm the partitions, and unmount them.

lsblk

sudo umount /mnt/sdcard

Run the following command to tell pmbootstrap to write the system directly to the SD card partition. You will need to set a password during the process.

pmbootstrap install --dev=/dev/mmcblk0

Alternatively, only create the image file:

pmbootstrap install

Then retrieve the image from the tmp directory:

pmbootstrap export

cd /tmp/postmarketOS-export

cp *.img /home/user/Downloads

Manually write the image contents to the SD card with dd:

sudo dd if=pine64-pinetab2.img of=/dev/mmcblk0 bs=1M status=progress conv=fsync