HowTo: UBports Installer & System Image (Halium 7.1) - ubports/porting-notes GitHub Wiki

So after a long journey in porting-land, you might end up with a port that is usable without too much hassle, and you want to widen the user base, also for having the benefit of automatic updates. But, getting the device into the installer can lead to some roadblocks, and we want to give a few hints here what to do to overcome them.

NOTE: This guide is valid for Halium-7.1 only at the time being!

First, we try to explain which parts are involved and how they play together:

The UBports installer is our comfort tool for users to get Ubuntu Touch booting without any command line magic or manual steps. It is responsible for:

• detecting the device before installation
• giving pre-installation instructions, like additional unlock steps
• letting the user select any of the available channels
• letting the user wipe all user data that was created by Ubuntu Touch. (It will not format the /data partition)
• letting the user choose to bootstrap the device, that means, flashing necessary partitions for the installation (other partitions might get flashed later by the system-image client)
• Transferring all installable content via adb into the device´s /cache folder (can be partition or loopmount on /data)

The system-image server is our repository for device images. It has to know about each device and the needed files to flash it. For each channel that is available to users a certain device needs to be created there. We will explain later on what you need to do to get your device registered.

The system-image server is responsible for:

• Serving a list of channels and devices in each channel
• Updating the devel and RC channels automatically (devel multiple times a day, RC weekly)
• Creating update deltas for up to 10 revisions in the past, to minimize download sizes
• Serving files and pgp signatures in a way so correctness for each flashable file can be guaranteed

Installation of initial system and updates is implemented into the UBports Recovery. One of the preconditions of getting an installable device image therefore is to have the recovery build for your device working. The recovery image is loosely related to the LineageOS recovery, with a few modifications. One of them is a script which we could call system-image client for simplicity, though the real system-image client is only installed in the rootfs itself.

The recovery is responsible for:

• Checking the instruction file from the installer
• Deleting/Formatting any partitions or data folders as needed
• Unpacking the root file system into /system partition
• Copying the system.img file into /system/var/lib/lxc/android folder
• Creating additional symlinks or directories as glue between Android image and Ubuntu Touch

And that's it! Now lets go through a few preconditions for making a device installable.

UBports Recovery is included already in the Halium manifest, but unfortunately not all necessary changes are already there. So first we need to add/replace a few repos in the manifest for your device. Please just the entire list from here:

    <remote name="beidl" fetch="https://github.com/fredldotme" />

    <project path="external/gpg" name="android_external_gpg" revision="halium-7.1" remote="beidl" />
    <remove-project path="external/toybox" name="android_external_toybox" />
    <project path="external/toybox" name="android_external_toybox" revision="halium-7.1" remote="beidl" />

    <remove-project path="system/core" name="Halium/android_system_core" />
    <project path="system/core" name="Halium/android_system_core" groups="pdk" remote="hal" revision="halium-7.1-adbroot" />

A few remarks:

• gpg is needed for checking file signatures
• toybox, system-core and recovery need to be replaced due to necessary changes and for getting an adb server which has authorization disabled

After you have applied these changes, you need to repo sync otherwise the changes won´t get imported. After that:

• Select the eng build instead of userdebug like this: lunch <devicename>_eng
• use mka recoveryimage to only update recovery
• Flash the resulting recovery.img
• Verify if you can adb shell into it

All updates first need to go to /cache folder, which is by default mounted to the cache partitions. Some cache partitions are really small, blocking us from using them. The cache partition should have at least 1GB of space. Boot into your recovery and check its size with df.

In case your cache partition is too small, you can try the following:

• Comment out the cache partition in your fstab file
• Add the following entry to your init.recovery.rc:

on post-fs-data
    mkdir /data
    mount ext4 /dev/block/<device-specific-subdir>/by-name/userdata /data
    mkdir /data/cache
    mount none /data/cache /cache bind
    mkdir /data/cache/recovery

This will ensure that data is mounted early and then create a cache folder there. This folder will then be mounted on /cache as bindmount, effectively redirecting all stuff to /data/cache. The device specific subidrectory can be obtained from the fstab file

Current system-image client cannot properly handle the Halium boot mode. So we need to let go our simple concept of having rootfs.img and system.img side by side. But halium-boot needs to know about it! So lets do the following:

• Add the following argument to your kernel cmdline in BoardConfig.mk: systempart=/dev/mmc... - To find out which mmc device node you need, do an ls -la /dev/disk/by-partlabel/system in the booted Ubuntu Touch system.
• Build halium-boot. Do NOT flash it now!
• Instead, go to fastboot mode and issue fastboot boot halium-boot.img to trigger a trial boot without flashing. This won´t bring you into a live system of course, as now the whole system stuff is expected to be in /system, which is probably empty. So you should get dropped to the emergency telnet mode.
• Try telnet 192.168.2.15 and inspect dmesg, it should confirm that it tries to mount /dev/mmc... to some place, but fails.

t.b.d.

Currently a device can only be installed if:

• it is built through our infrastructure and
• The manifest is in the halium-devices repo (https://github.com/Halium/halium-devices)

Open an issue here https://gitlab.com/ubports/community-ports/general/-/issues, describing your request. Add the device codename. We might come back with additional questions.