Porting to a new device
Please write your porting progress to the devices page, even if you didn't get very far. This helps to determine what can be improved to make porting easier.
Please use a spare device for experimenting with postmarketOS! You won't be able to use typical phone features right now, such as making calls, writing SMS, using Wi-Fi, using Bluetooth. Although everything has been tested, there is no guarantee that you won't break your device.
- Clone the repository:
git clone https://github.com/postmarketOS/pmbootstrap
./pmbootstrap.py initand configure for a new device
- Open a second terminal and run
./pmbootstrap.py logto get detailed output from the following pmbootstrap commands
Create an appropriate
device-$vendor-$name package in the
cp -r aports/device/device-samsung-i9100 aports/device/device-vendor-name
The important files are
APKBUILD (build recipe, Glossary#apk) and deviceinfo reference. Please adjust them as necessary. Note that if your device uses fastboot, you will need to add
mkbootimg to the
depends= list in the
APKBUILD, and the following variables at the end of
deviceinfo (guide, example):
# Fastboot related deviceinfo_generate_bootimg="true" deviceinfo_flash_offset_kernel="" deviceinfo_flash_offset_ramdisk="" deviceinfo_flash_offset_second="" deviceinfo_flash_offset_tags="" deviceinfo_flash_pagesize=""
A post-install script can be created to append device-specific partitions to
/etc/fstab. See the post-install script for
device-nokia-rx51 for an example.
Once the device package is configured, you will need to update checksums in the APKBUILD to match the new configuration files. You can do that by running:
./pmbootstrap.py checksum device-$vendor-$name
Now, you can build your device package with:
./pmbootstrap.py build device-$vendor-$name
While the goal is to use a mainline kernel for all devices in the long run, this certainly can not be done in one step when porting to a new device. Create a new package for the kernel by copying the kernel package of the most similar device with an existing port. For example:
cp -r aports/device/linux-lg-mako aports/device/linux-vendor-name
Now edit the
APKBUILD. Replace the kernel source with a kernel suitable for your device. For Android devices we usually use the kernels from LineageOS. Copy the right defconfig from your kernel's source folder into your new
linux-... folder and adjust its file name. Please adjust the comments in the
APKBUILD file about which defconfig you have used, and which modifications you have made. Please also adjust the
pkgrel to match the kernel version.
Next, generate the checksum for the kernel package files using:
./pmbootstrap.py checksum linux-$vendor-$name
Now, before building the kernel itself, it is required to run the kernel's menuconfig with:
./pmbootstrap.py menuconfig linux-$vendor-$name
The first time, you run the menuconfig command, you will get prompted about new config options, that the default config does not address (in Android's build process, these options get ignored, but in pmOS they must be specified). Please accept the defaults it presents. After that, you will be shown a menu, in which the
DEVTMPFS kconfig flag should be enabled, to get udev working, which is needed for touchscreen support in Weston. It should be located under
Device Drivers ---> Generic Driver Options. NOTE: Do NOT set
DEVTMPFS to automount.
Once you have configured the kernel, build it (the arch specification is necessary here, because we're really compiling code - the device package just contains text/scripts and no native code, therefore it is architecture independent):
./pmbootstrap.py build linux-$vendor-$name --arch=armhf
linux-lg-mako package has a patch called
gpu-msm-fix-gcc5-compile.patch, to fix compiler errors with GCC6. If your kernel doesn't need that specific patch (if it does not apply correctly, as in this report), just remove the file, and remove it from the
source= line in the
If your manufacturer has not released the source code of your kernel and you don't want to give up on porting your device, you can try the prebuilt kernels approach.
Appended device trees
Some devices need an appended device tree to boot. In LineageOS kernels this will mean that beside the generated
zImage there is also a
zImage-dtb file. To use this you have to enable in your kernel appending the
dtb as in lg-hammerhead and change the package step in the build script to use the
# Change zImage to zImage-dtb on this command: install -Dm644 "$srcdir/build/arch/arm/boot/zImage-dtb" \ "$pkgdir/boot/vmlinuz-$_flavor"
In Android kernels, you usually enable
BUILD_ARM_APPENDED_DTB_IMAGE and get an image with
dtb appended and the filename will be
In the mainline kernel instead, you enable
ARM_APPENDED_DTB (without trialing **_IMAGE**) and will get a bunch of
.dtb files for the boards that are selected in the kernel config. In this case you need to manually append the correct
.dtb file to the compiled kernel image
zImage. An example of this is in the kernel package for the nokia n900:
cd "$srcdir/build/arch/arm/boot" cat zImage dts/omap3-n900.dtb > zImage-dtb
If you are unsure, whether your device has an appended dtb file, use extract-dtb on an existing kernel image (e.g. from LineageOS).
extract-dtb is packaged for postmarketOS, you can build it with
pmbootstrap build extract-dtb.
If you want to install to the system partition of an image file, run the following:
If you want to install to a SD card, insert it and run the following. Replace mmcblk0 with the actual device name (
lsblk is handy to find out the correct device name).
./pmbootstrap.py install --sdcard=/dev/mmcblk0
Before you can run any flash command, you must put your device in the flashing mode. It is usually done holding Volume Down & Power simultaneously when the device is switched off but it may vary depending on the device. For more information see the specific page for your device in the LineageOS Wiki.
If you want to install to the system partition, run the following (not for the SD card installation!):
./pmbootstrap.py flasher flash_system
If the system partition for your device is less than 850MB, you should find the size and change the value of
install_size_system in the file
If you have a device, that works with fastboot, you can boot the kernel now without flashing it:
./pmbootstrap.py flasher boot
Otherwise, you will need to flash the kernel to the device boot partition:
./pmbootstrap.py flasher flash_kernel
Alternative to flashing: export
If the flashing method does not work, it is also possible to export all generated image files to a specific directory (with symlinks), so you can flash it manually with your host Linux system (or even on Windows with proprietary flashers such as Odin, if this is the only way it works for you):
./pmbootstrap flasher export
If you are lucky, your screen may give some clues that you are booted into pmOS. If not, do not get discouraged, the graphics on your device may not yet be setup correctly. The next steps are to see if you can connect to the device through telnet over USB. See the Inspecting the initramfs page for more details.
Also check Tuning sysfs.
Don't forget to create a specific wiki page for your device, and add it to the devices page. If you noticed anything that was unclear or discovered something useful, please help to improve the wiki!
Feel free to ask / help on IRC or Matrix group