Jump to content

Porting to a new device/Initialization

From postmarketOS Wiki

Initialization

Before pmbootstrap can be used, a number of configuration questions need to be answered. The sections below go into detail for the various questions.

$ pmbootstrap init

If you already ran this before, run the following to update your local clone of pmaports.git instead:

$ pmbootstrap pull

Work path

Is a place where all pmOS-related files will be stored.

Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there.
Work path [/home/user/.local/var/pmbootstrap]:

pmaports path

Should accept default option.

Location of the 'pmaports' path, containing package definitions.
pmaports path [/home/user/.local/var/pmbootstrap/cache_git/pmaports]:

Channels

Choose edge here. Stable releases are not recommended for development.

Choose the postmarketOS release channel.
Available (11):
* edge: Rolling release / Most devices / Occasional breakage: https://postmarketos.org/edge
* v24.12: Latest release / Recommended for best stability
* v24.06: Old release (unsupported)
Channel [edge]:

Basic device information

Type in the vendor and codename of your device to start a new port, and answer each prompt. For help, see how to find device-specific information.

Choose your target device vendor (either an existing one, or a new one for porting).
Available vendors (94): acer, alcatel, ..., zte, zuk
Vendor [generic]: wiki

Device codename: example

Device architecture (riscv64/ppc64le/armv7/x86/x86_64/aarch64) [aarch64]:

Who produced the device (e.g. LG)?
Manufacturer: Samsung

What is the official name (e.g. Google Nexus 5)?
Name: Wiki Example

In what year was the device released (e.g. 2012)?
Year: 2016

Device type

Choose handset if the device is a phone.

What type of device is it?
Valid types are: desktop, laptop, convertible, server, tablet, handset, watch, embedded, vm
Chassis: handset
Does the device have a sdcard or other external storage medium? (y/n) [n]:

Flash method

It depends on the flashing protocol that comes with the device. For most Android devices, this is fastboot, some Samsung models need heimdall (which is compatible to "Odin"), MTK devices use mtkclient, and Maemo/MeeGo-based Nokia phones work with 0xffff. If you don't know which one it is, try to enter the bootloader on your device and check what mode it shows. Most of the time that can be done by pressing the Volume Down key when it's booting. In case you can't figure that out, try to search the internet.

For more information see the wiki page about Deviceinfo flash methods.

Which flash method does the device support?
Flash method (0xffff/fastboot/heimdall/mtkclient/none/rkdeveloptool/uuu) [none]:

Depending on your selection, pmbootstrap may ask you to analyze a boot.img file to get offset values required for the flash method. Get the right one for your device from TWRP (twrp-*.img), LineageOS (boot.img inside the zip archive) or by extracting it from within a running Android. If you can't find any, you can skip this step for now by just pressing the return key.

You can analyze a known working boot.img file to automatically fill out the flasher information for your deviceinfo file. Either specify the path to an image or press return to skip this step (you can do it later with 'pmbootstrap bootimg_analyze').
Path: /home/user/Downloads/twrp-3.2.0-0-mako.img

Interfaces

Note Don't choose Plasma Mobile, Phosh or Sway if you're using a downstream kernel for porting.

We recommend that you start with xfce4 first, because while it is not really suitable for a phone, it has a high chance of working due to that it uses X.Org which has a fbdev backend unlike most Wayland compositors which require working DRM (Direct Rendering Manager, which generally only works properly on close-to-mainline kernels). After that one works, feel free to try out another interface (but expect that it will not necessarily work out of the box).

Username [user]:
Available user interfaces (22): 
* none: Bare minimum OS image for testing and manual customization
* asteroid: (Wayland) Smartwatch UI from AsteroidOS
* bananui: (Wayland) Keypad controlled UI for feature phones
* buffyboard: Plain framebuffer console with modern touchscreen keyboard support
* cage: (Wayland) Kiosk WM
* console: Console environment, with no graphical/touch UI
* fbkeyboard: Plain framebuffer console with touchscreen keyboard support
* framebufferphone: Minimalist framebuffer menu/keyboard UI
* gnome: (Wayland) Gnome Shell
* gnome-mobile: (Wayland) Experimental Gnome Shell for phones
* i3wm: (X11) Tiling WM (keyboard required)
* lomiri: (Wayland) The convergent desktop environment (Experimental)
* lxqt: (X11) Lightweight Qt Desktop Environment
* mate: (X11) MATE Desktop Environment
* mediaberry: (Wayland) Platform for streaming boxes and smart TVs (WIP)
* moonlight: (Wayland) Open Source PC client for NVIDIA GameStream
* openbox: (X11) Lightweight X11 window manager
* os-installer: UI for installing postmarketOS
* plasma-desktop: (X11/Wayland) KDE Desktop Environment
* shelli: Plain console with touchscreen gesture support
* sxmo-de-dwm: Simple Mobile environment based on SXMO and dwm
* sxmo-de-sway: Simple Mobile environment based on SXMO and sway
* xfce4: (X11) Lightweight desktop
NOTE: 7 UIs are hidden because "deviceinfo_gpu_accelerated" is not set
User interface [console]: 

SystemD

Warning WARNING: Check kernel requirements for SystemD in SystemD's README. Enabling it for unsupported kernel version will lead to broken pmOS installation.
Note At the time of writing (April 20th, 2025), minimal supported kernel version for SystemD 257 is 5.14. Some kernel sources include patch backports to make SystemD work on older kernels, though it's not very common.
Based on your UI selection, 'default' will result in installing systemd.
Install systemd? (default/always/never) [default]: 

Additional options

Build options: Parallel jobs: 3, ccache per arch: 5G
Change them? (y/n) [n]:

Additional packages that will be installed to rootfs. Specify them in a comma separated list (e.g.: vim,file) or "none"
Extra packages [none]:

Your host timezone: Europe/London
Use this timezone instead of GMT? (y/n) [y]:
WARNING: The applications in the chroots do not get updated automatically.
Run 'pmbootstrap zap' to delete all chroots once a day before working with pmbootstrap!
It only takes a few seconds, and all packages are cached.
Done!

Logging

Open a second terminal and run the following command to see detailed logging (such as compiler output). Whenever reporting that something does not work, please attach the detailed log output from this window.

$ pmbootstrap log

Logs can be found in log.txt inside work path.

~/.local/var/pmbootstrap/log.txt