Device specific package

From postmarketOS
Jump to navigation Jump to search

We aim to have ideally only one device specific package. Other packages should be shared between all devices.

However, in practice, we need an extra package for the kernel (unless the device has been mainlined). And sometimes one for device specific firmware (in theory it is possible to divide these in the firmware files for specific chips, and then share these chip-specific firmware packages across multiple devices, but we're not quite there yet).

Every device specific package contains at least the deviceinfo file, and the APKBUILD. This article describes special characteristics of the device APKBUILD.

Generate a template

The recommended way to start with a new device package is using pmbootstrap init and typing in a new device name. But it is also possible to directly call the device package wizard with pmbootstrap aportgen device-changeme-changeme (adjust changeme accordingly).


In order to share code between the APKBUILDs of these packages, all new device packages depend on a devicepkg-dev package and call its functions inside their APKBUILDs:


build() {
	devicepkg_build $startdir $pkgname

package() {
	devicepkg_package $startdir $pkgname

The variables $startdir and $pkgname are always available where they are used, and must be passed to these functions. devicepkg_build and devicepkg_package are simple shell scripts, and they get packaged from here.


Optionally creates an udev rule for the device's touch screen, based on the data from the deviceinfo. We can extend this to do more when it makes sense.

The source code is in of the devicepkg-dev pmaport.


Installs the deviceinfo file (to /etc/deviceinfo) and all other files, that may have been generated during devicepkg_build.

The source code is in of the devicepkg-dev pmaport.

Use install_if to pull in packages

If your device requires a specific X11 driver for example, it is possible to say: "Install this driver when this device package and Xorg are installed.".

Here is one example from device-qemu-amd64:


x11() {
	install_if="$pkgname xorg-server"
	mkdir "$subpkgdir"

We only create the $subpkgdir, because building subpackages fails, when the subpackage folder does not exist. You can add multiple subpackages per package, see APKBUILD_Reference#subpackages.

Add a device specific config file

It might be, that you would like to disable Xweston for your device, because it does not work and then weston does not start. To accomplish this, we will also make use of install_if and a subpackage. But this time we won't pull in another package, but install the config file:

source="deviceinfo weston.ini"

weston() {
	install_if="$pkgname weston"
	install -Dm644 "$srcdir"/weston.ini \

This will only install the custom Weston config, when weston is installed. The $subpkgdir is implicitly created with install -D.

Proprietary firmware or userland blobs

The actual blobs don't belong into the device package, but into their own package:

  • Either a linux-firmware-* package from Alpine
  • Or a firmware- package (for firmware, use another name for userland blobs) from postmarketOS' aports
    • check out the existing ones we already have for reference.

Once you have that package, modify your device package:

  • Add $pkgname-nonfree-firmware:nonfree_firmware or $pkgname-nonfree-userland:nonfree_userland to the subpackages="" line
    • Do not replace the $pkgname variable.
    • If you're packaging both firmware and userland blobs, then add both subpackages.
  • Add a block based on the following at the end of your device package's APKBUILD, before the sha512sums.
    • Replace nonfree_firmware with nonfree_userland depending on what you're packaging.
    • Change firmware-motorola-titan to the blob package that you found/made for your device.
    • Adjust the pkgdesc accordingly. It will be shown to the user in pmbootstrap init when deciding how libre they want their postmarketOS installation to be.
    • Keep the $subpkgdir variable, that variable exists in this context.
nonfree_firmware() {
	pkgdesc="Wifi firmware"
	mkdir "$subpkgdir"

Update the checksums and rebuild your device package.

Multiple kernels

This is relevant in case it is possible to boot your device with multiple kernels (most common case is the downstream kernel from the vendor linux-$devicename, and one of the upstream linux-postmarketos-* kernels).

  • Remove the current kernel package from depends of your device's APKBUILD
  • Add the kernel subpackages and subpackage functions. One example from device-sony-amami:
kernel_downstream() {
	pkgdesc="Display and wifi works (see device table for details)"
	devicepkg_subpackage_kernel $startdir $pkgname $subpkgname

kernel_mainline() {
	pkgdesc="For kernel development only (most features aren't working)"
	devicepkg_subpackage_kernel $startdir $pkgname $subpkgname
  • Additionally in your deviceinfo file you can use the suffix from your kernel subpackage (e.g. _mainline or _downstream) to limit the variables to one kernel variant in case you need different values. An example:
  • Also consider adjusting the dependencies of your device package to not include downstream- or mainline-specific helper packages, such as adsp-audio, wcnss-wlan or msm-modem-downstream. You can use device-fairphone-fp2 as an example for that.
  • Run pmbootstrap init afterwards to test the change. It should ask you for the kernel now.
  • See device-qemu-amd64 for another example.
  • Implementation details and discussion in #1363

Initramfs hook

Some devices need to run special commands at boot time, for example turning on the display or kicking a watchdog. It is possible to do this with a device specific initramfs hook.

Create a new file in your device package's dir and fill it with the command that needs to be executed, along with a comment describing what it does:


# set usb properties
echo 4 > /sys/devices/platform/android_usb/usb_function_switch

Then open the APKBUILD and add to source=.

As usually, update the checksums, build the package with --force and test the hook on your device.


If you have a modern device-specific APKBUILD (i.e. because you have just generated it), it will use devicepkg_package in package(), which will detect the initfs hook and install it automatically (pmaports!191). This is the preferred way to do things. Otherwise you would have to copy this install command to the end of your package() function.

For reference, you can look at the existing initfs-hooks:

$ cd ~/code/pmbootstrap/aports/device
$ find -name

See also