移植简介#

第一节将向您介绍将 Ubuntu Touch移植到安卓设备的细节。请注意,它是针对一般用户而非有经验的移植开发人员准备的。在随后的章节中,我们努力使正文更加简洁,以满足经验丰富的读者的需要,同时为经验不足的读者提供补充阅读的链接,从而使之有所区别。

这篇教程介绍了理想情况下移植的一系列步骤。但是,移植工作经常会遇到烦人的问题。每一个设备都不一样,而且实际上你可能会重复,跳过一些步骤以及发现新的和搜不到的问题。

什么是Ubuntu Touch?#

Ubuntu Touch 是一个开源的手机系统。它可以被移植到装有安卓的手机上。不过,大部分的设备上依赖一些专有软件。

To be specific, device vendors tend to keep the code that speaks directly to the device hardware (the low level device drivers) proprietary. These components are commonly called the vendor ‘blobs’ (Binary Large OBjects). The vendor blobs need to be incorporated into an Ubuntu Touch port. Note that these components are specific not only to each device, but also to each Android version. It is therefore necessary to secure the correct version of these components when building a port.

这就是为什么 Ubuntu Touch 不能为大多数商业设备完全从源代码构建。相反,将系统移植到这些设备上,需要将前面提到的 vendor blobs 整合到系统的其他部分,而这些部分可以从源代码中构建。

The next component of Ubuntu Touch is a pre-compiled root filesystem which needs to be installed on the device. This component does not communicate directly with the device hardware. Instead, this communication is mediated by a Hardware Abstraction Layer (HAL) which needs to be built for each specific device, because each device has its specific hardware architecture. This component is called Halium and is available in different versions (5.1 which is largely obsolete, 7.1, 9, 10 and 11 as of writing) corresponding to different Android versions.

The Halium project enables Linux systems to run on Android hardware. It is a joint effort by multiple mobile operating systems, notably Lune OS and UBports.

UBports porting builds on top of Halium porting. Consequently, you will be using both the Halium porting guide and the UBports porting guide. At times it may also be helpful to test with one of the other operating systems to debug a problem from different angles.

Halium is an indispensible part of an Ubuntu Touch port and is available in the form of open source software. Developing a new version of Halium is a very considerable task which is why only a few versions of Halium are available. Each port of Ubuntu Touch has to be based on one of the available Halium versions and vendor blobs from the corresponding Android version. See the first two columns of the table below for details.

所以一个Ubuntu Touch移植基于以下部件:
  • Ubuntu Touch根文件系统 (rootfs)

  • Halium (包含在启动(boot)和系统镜像(system images)中)

  • 制造商驱动

You, the porter, need to build Halium (in part or in whole, depending on porting method) and install this together with the Ubuntu Touch rootfs in order to create a functioning Ubuntu Touch port.

Android and Halium versions#

Halium is built using source code for a modified version of the Android operating system called LineageOS (see the LineageOS website and wiki). The required source code is available online and needs to be downloaded and configured to build the correct Halium version for each individual device port. The table below shows which versions are required for the different Halium versions.

安卓版本

Halium版本

Lineage OS (LOS)

7.1

7.1

14.1

9.0

9.0

16.0

10.0

10.0

17.1

11.0

11.0

18.1

Generic System Image#

Starting with Android version 9.0, a significant change of architecture was introduced. The device-specific vendor blobs now reside on a separate partition instead of sharing a partition with the rest of the system image. This separation of device-specific code from generic code made possible what is known as the Generic System Image (GSI).

A GSI is a system image that is built to be able to function with a wide range of devices. Android devices, as of version 9.0, use a GSI. For more information, see the Android Developer pages

The development of the Android GSI architecture also cleared the way for the now available generic Halium 9.0 arm64 system image (hereafter referred to as the Halium GSI, or simply the GSI) which is used for Ubuntu Touch. This, however, is somewhat different from the Android GSI. For a more detailed explanation of the Halium GSI, please refer to the wiki page on Gitlab CI builds of the generic Halium system image.

What does this mean for the porting process?#

Since the GSI is a prebuilt, device-independent component, it effectively simplifies the task of building a viable port by removing much of the meticulous and time consuming task of getting the hardware-specific vendor blobs compiled into the system image and configured to function properly.

Porting methods#

This guide documents three different porting methods, which we call: Full system image method, Halium-boot method, and Standalone kernel method. When porting based on Halium 7.1 the Full system image method is the only available method to follow. For Halium 9.0 all three methods are possible.

Full system image method#

This porting method requires building both the boot image (halium-boot.img) and the full device specific system image (system.img) from source and installing these together with the UBports root file system (rootfs). For Halium 7.1 ports this is the only possible method (Consequently, this method is sometimes referred to as the Halium 7.1 method). For Halium 9.0 it is also possible to use this method, however for Halium 9.0 the other two methods below are probably easier.

Halium-boot method#

For this porting method it is sufficent to build the halium-boot.img and install this together with the Halium GSI and the UBports rootfs. This method can be used for Halium 9.0 ports.

Standalone kernel method#

This porting method only requires building the kernel and installing this together with the Halium ramdisk, the Halium GSI and the UBports rootfs. This method can be used for Halium 9.0 ports.

All methods share some common steps. However, there are also significant differences that must not be missed. Therefore, the methods will be treated separately in the subsequent sections where needed.

The remainder of this section gives some words of advice to new porters. If you already have porting experience or ROM building experience, you can likely skip straight to Preparations.

移植过程中的挑战#

Building the necessary components and getting them to work together properly always involves an amount of code modifications, configuring and testing, but considerably moreso when doing full system image builds, compared to builds using the GSI (see porting methods).

Luckily, there is a community of porters out there who are eager to see Ubuntu Touch ported to new devices. When you run into trouble, you should search the sources below (获取社区帮助) to see if others before you have solved the issue. There are online Telegram chat groups you can join to ask for help, but please bear in mind that those participating are doing so in their spare time.

预备的知识和技能#

Porters come in all sizes and shapes, so to speak. Therefore, this guide does not presuppose extensive knowledge or skills in any particular field. You should, however, as a bare minimum be familiar with some common shell commands and be comfortable working from the terminal on you host PC. Furthermore, the guide is based on a host PC running Linux. If you have some knowledge of programming, this will come in handy at some point, especially if you are familiar with C / C++. Also, you should familiarize yourself with git and set up a Github or Gitlab account to keep track of your code changes. It is wise to start documenting your steps from the very beginning.

We have attempted to give a certain amount of explanation along the way. However, this guide is not an in-depth reference into the architecture and inner workings of Ubuntu Touch, and gaining a deeper understanding will consequently require an amount of research on your part.

获取社区帮助#

当你遇到麻烦时(你肯定会遇到的),请参考以下一个或多个来源:

一般性建议#

The more rigorous you are at making notes and documenting your steps, the less time you will spend backtracking your steps and guessing your way along. When dealing with issues that arise along the way, it is wise to work on them one at a time. If you try to correct several things at once, you risk ending up trying to guess which changes solved a given issue, which easily leads to breaking the functionality in question once more at some later stage.

If you are not discouraged after reading this, we welcome your efforts and wish you the best of luck!

The next section presents a key to the rest of this guide.