Porting to a new device/Initialization
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
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: Check kernel requirements for SystemD in SystemD's README. Enabling it for unsupported kernel version will lead to broken pmOS installation. |
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