Overlay file method

The UBports rootfs comes with a set of standard configuration files for a number of features such as display scaling, sound, bluetooth and more. These files may not tailored to the needs of your specific device and must therefore to be replaced in order for the feature in question to function as it should. This is done with overlay files, i.e. files that the original files get overwritten with. In other words, you need to rewrite the files in question, making the necessary adjustments for your device, and then see to it that these are incorporated into the build so that they will replace the originals.

If your build is based on the downloaded GSI and rootfs, installed using the halium-install script, then further adjustment of the build will not be possible. This is because the halium-script does not include any method for injecting overlay files. If, on the other hand, your build is based on Gitlab CI scripts, there is a way to further tweak your port with overlay files. This method is described at the end of this section.

Configuring features with overlay files

For full system.img-based builds, irrespective of Halium version, the method described below applies if the file you need to edit can be found in the /etc directory (or a subdirectory of this) on your device. In other words, the file or files you wish to overlay must actually exist and be located where specified above. You should not attempt to overwrite files located elsewhere using the method described here.

If your port is based on Gitlab CI scripts, it is actually possible to not only overlay existing files, but also introduce files that were not originally present. The method for Gitlab CI script based builds is detailed at the end of this section. If this is the method you will be using, you should still read both sections to gain a better understanding of how this method actually works.

Overlay method for full system.img builds

В каталоге устройства создайте папку с названием „ubuntu“.. Скопируйте сюда все файлы, которые хотите добавить в свою сборку.

Примерный список нужных файлов (неполный):
  • 70-android.rules

  • android.conf (для масштабирования экрана, подробнее см. ниже)

  • touch.pa (для настройки/ инициализации звука pulseaudio, подробнее см. ниже)

Затем содержимое этих файлов добавляется к файлу device.mk в каталоге устройства. Для трех выше перечисленных файлов нужно добавить следующий код:

### Ubuntu Touch ###
    $(LOCAL_PATH)/ubuntu/70-android.rules:system/halium/lib/udev/rules.d/70-android.rules \
    $(LOCAL_PATH)/ubuntu/android.conf:system/halium/etc/ubuntu-touch-session.d/android.conf \
### End Ubuntu Touch ###

The first of these three files, 70-android.rules, is the one you created when bringing up Lomiri. You can extract this file from the device using adb pull or scp and copy it to the „ubuntu“ directory of your device source tree, making sure to add the corresponding line to your device.mk file, as described above.


The string before the colon „$(LOCAL_PATH)/ubuntu/70-android.rules“ specifies the path to the source file to be injected. The string after the colon „system/halium/lib/udev/rules.d/70-android.rules“ specifies the target location on your device.

Таким образом, необходимо выполнить следующие шаги:
  1. Скопируйте файл, который требуется изменить, в каталог „ubuntu“ , который был создан в исходном дереве устройства.

  2. При необходимости отредактируйте файл.

  3. Добавьте строку в раздел PRODUCT_COPY_FILES файла device.mk, как показано выше.

  4. Пересоберите файл system.img и перепрошейте его с rootfs.


Каталоги для файлов, упомянутых выше, выбираются не случайным образом. Следует использовать только указанные директории.


Когда будет указан целевой путь „system/halium/etc/myfilename“, файл „myfilename“ окажется в каталоге „/etc“ устройства (то есть без начального „system/halium“)

Пересборка образа system.img

For Halium-7.1 ports and Halium-9.0 ports using a device specific system.img in place of the GSI, the system.img now needs to be rebuilt.

When you have made the adjustments you need and prepared your source as described above, rebuild the system image: mka systemimage.

When rebuilding the system image after small changes like these, you need not mka clean first. However, changes to PRODUCT_PROPERTY_OVERRIDES might not get detected by the build system. To ensure this, go to the directory BUILDDIR/out/target/product/CODENAME/system and delete the file build.prop before rebuilding.

Overlay method for Gitlab CI script-based builds

Builds in this category can also be adapted to a particular device using overlay files, and when building by this method (see Halium-9.0 - Using Gitlab CI scripts) it is possible not only to replace existing files, but also to introduce new ones.

When you have prepared the files to replace or introduce, and determined the exact locations where they need to go on your device, these locations need to be replicated under the directory overlay/system/ before running the Gitlab CI scripts according to the instructions included.

For example:

The udev rules file 70-android.rules needs to go into system/halium/lib/udev/rules.d/. This is accomplished by first creating the directory in the Gitlab scripts build tree. Standing in the root of this tree, first create the directory and then copy the file to this location:

mkdir /halium/lib/udev/rules.d
cp <path-to-70-android.rules> /halium/lib/udev/rules.d/70-android.rules

Now run the build scripts and the file will get incorporated into your build. Flash the files as per the instructions.