Sailfish OS 移植文档

第一章 概览

1.1 目标

通过本指南，您可以在现有的 Android 内核和驱动程序上，移植一个可以在安卓设备上运行的 Sailfish OS。

它包括：

• Sailfish 核心：GNU/Linux 的用户空间核心

• Android 的硬件适配，包括：

  • 每个型号的设备独有的安卓内核

  • 安卓底包，可以是以下几个：

  • • LineageOS - https://wiki.lineageos.org
    • AOSP - 安卓开放源代码项目 - https://source.android.com
    • CAF - Code Aurora Forum - https://www.codeaurora.org
    • 索尼开放设备计划（Sony Open Devices program） - https://developer.sony.com/develop/open-devices
    • 供应商提供的特定底包

• Sailfish OS 的组件

1.2 开发

1.2.1 要求

开发环境包括平台的SDK，以及：

• 一个或多个特定设备的 target（带有设备特有的头文件和库的根文件系统）

• HA build SDK （构建Android 源代码所需最基础的Ubuntu chroot）

在硬件适配开发过程中，通常会使用两个窗口或终端，一个运行HA build SDK 来使用Android代码进行构建和工作；而另一个用Platform SDK构建用于硬件适配的RPM。

如何建立Platform SDK，以及用于特定设备的 Ubuntu chroot，详见第4.1节。

Platform SDK会话的命令和输出，在代码块顶部使用 PLATFORM_SDK $ 表示，如下所示：

PLATFORM_SDK $
echo "run this command in the Platform SDK terminal"

如何输入 PLATFORM_SDK $ 详见第4.2节。

HA build会话的命令和输出在代码块顶部使用 HABUILD_SDK $ 表示，如下所示：

HABUILD_SDK $
echo "run this command in the Ubuntu HA build SDK terminal"

如何输入 HABUILD_SDK $ 详见第4.3.2节。

1.2.2 构建区根目录

在本指南中，我们引用托管环境变量 $ PLATFORM_SDK_ROOT 的SDK目录托管 Platform SDK，Targets 和 Ubuntu chroot。 一个SDK target 约 0.5-1GB，您总共需要大约3GB的空间。

1.2.3 构建组件

有许多需要构造的组件；更底层的以及与 Android 有关的组件是在 HA build SDK 中构建的；其余的则是在 Platform SDK中构建。

• 在 HA build SDK 中有：

  • 一个内核

  • 一个支持各种启动选项的 initrd

  • hybris-boot.img 和 hybris-recovery.img (用来启动和故障排除)

  • 一个基础Android的 /system/ 树

  • 一些安卓中为了与 libhybris 和 Sailfish 兼容而经过修改的部分（比如 Bionic libc, logcat, init, . . . )

• 在 Platform SDK 中有：

  • RPM软件包，包含所有内置的二进制文件和提取的配置。

  • 特定硬件的中间件和插件（例如 Qt QPA插件，PulseAudio）

为了方便分发，RPM软件包 已经被上载到了 HA 特定的存储库。通过这个库，可以使用 mic utility 来获取完整的系统映像。mic utility 也可以在Platform SDK 中运行。

1.3 部署

hybris-boot（ 包含内核与我们定制的 initrd ） 被刷入系统，同时 Sailfish OS 的 rootfs 则被放到 /data/ 的子目录，与没有经过修改的Android 系统共存并划分开来。

Sailfish OS 的 rootfs 接下来会被用做 switchroot 的 target ，并带有 /data 挂载绑定，以共享访问用户数据。

第二章 前提条件

2.1 移动设备

• 截至 2019.9.30 ，LineageOS 15.1（Android 8）和 LineageOS 16.0（Android 9） 官方支持的设备。而 CyanogenMod 的 10.1.x，11.0，12.1，13.0，14.1等版本则需要更多的努力，因为CM已经过时了。更多受支持的安卓版本也可以在这里查看。

  • 我们还支持索尼开放设备项目（SODP），并发表了以下几个设备重新构建可刷写镜像的指导方法：

    • Xperia X （Sony Aosp 6）
    • Xperia XA2 （Sony Aosp 8）
    • Xperia 10 （Sony Aosp 9）

  • 从CM13.0（Android 6）开始，Sailfish OS 已经添加了对64位 ROM 的支持：通过运行 64 位 Linux 内核和 Android HAL 的混合体来实现，而 Sailfish userspace 则以32位模式运行。

  • 访问 https://wiki.lineageos.org/devices 以查看受兼容的设备。

  • 访问 https://wiki.merproject.org/wiki/Adaptations/libhybris 来查看已移植的设备的状态列表。

  • 有关早期阶段的端口列表，请参见https://wiki.merproject.org/wiki/Adaptations/libhybris/porters，其作者可以在IRC上进行联系。

  • AOSP 或 CAF Android 底包的支持也已经提供，但是我们选择了 LineageOS 来更广泛地支持更多的设备。搬运者要用hybris 补丁来为 AOSP / CAF 的底包打补丁。 其它在使用上的差距很小（例如，使用 Lunch 命令而不是 Breakfast ）

• 备份好你的数据并确保你会救砖。

2.2 构建要求

• 一个 64位 Linux 内核的 64 位 x86 计算机
• Sailfish OS Platform SDK (安装方法将在后面介绍)
• Sailfish OS Target (将在后面介绍)
• 完整的安卓版本需要至少 30 GB 的硬盘剩余空间（ 20G 用来下载源码 ，剩下的用来构建 ）；HA build 和下载最基础的文件，则只需要很少的空间。
• 至少 4G 的运存（越大越好）

第三章 准备你的设备

请确保您可以备份和还原设备，并且了解设备恢复选项。 这不仅在刷入使用本指南构建的镜像时特别有用，而且在您要将设备恢复为出厂的Android状态时都非常有用（请注意，并非所有Android供应商都提供原厂镜像，因此您可能需要创建您现在正在使用的Android 系统的完整备份，并将其存储在安全的地方，然后再开始清除数据和刷入自定义镜像。）

3.1 备份并验证您的设备

1、刷机有风险！！！

2、先为你的手机刷入twrp

3、在twrp中备份

4、确保你可以用twrp恢复备份

3.2 刷入并测试你的安卓底包

刷入与你设备型号所对应的LOS底包，并确保它可以正常开机。

确保你的：OpenGL ES 2.0、WLAN、扬声器、蓝牙、NFC、SD卡、USB、电话、GPS、各种传感器、呼吸灯、相机、按钮、视频输出、屏幕背光、电池信息、收音机等各部分没有问题。

记下来有问题的地方，因为在移植完 Sailfish 后它们仍会有问题。

第四章 设置SDK

4.1 设置环境变量

在本指南中，我们将引用您的SDK，目标和源代码的位置。 按照Android硬件改版的惯例，脚本和配置文件中都同时使用了设备供应商（$ VENDOR）和设备代号（$ DEVICE）。

在本指南中，我们将以Nexus 5为例子，用CyanogenMod 11.0 作为底包进行移植。因此，请确保您仔细阅读了代码片段，并根据所移植的设备/供应商/底包进行了适当的重命名。

现在，在适合您的设备的主机操作系统上运行以下命令并开始设置：

HOST $
cat <<'EOF' > $HOME/.hadk.env
export PLATFORM_SDK_ROOT="/srv/mer"
export ANDROID_ROOT="$HOME/hadk"
export VENDOR="lge"
export DEVICE="hammerhead"
# 即使要移植64位设备，也将arch设置为armv7hl
export PORT_ARCH="armv7hl"
EOF
cat <<'EOF' >> $HOME/.mersdkubu.profile
function hadk() { source $HOME/.hadk.env; echo "Env setup for $DEVICE"; }
export PS1="HABUILD_SDK [\${DEVICE}] $PS1"
hadk
EOF

这样可以确保你在使用 ubu-chroot 命令来进入 Android SDK 时，环境已经是搭建好的。

这同时还创建了一个 hadk 函数，可以用来建立或重设环境变量。

4.2 安装 Platform SDK

在 Sailfish OS wiki 上找到说明：https://sailfishos.org/wiki/Platform_SDK_Installation

（“Quick start”部分就已经够了，先不要安装 SDK Targets）

之后，暂时离开 PLATFORM SDK，以使用以下必要的命令，为新创建的 〜/ .mer sdk.profile 赋值：

PLATFORM_SDK $

exit
HOST $
cat <<'EOF' >> $HOME/.mersdk.profile
function hadk() { source $HOME/.hadk.env; echo "Env setup for $DEVICE"; }
hadk
EOF

sfossdk

你现在需要一些工具，它们并不被 Platform SDK 默认包含。

• android-tools-hadk 包含使用Android SDK所需的工具和实用程序
• tar 用来提取 ubu-chroot 镜像

PLATFORM_SDK $

sudo zypper ref
sudo zypper in android-tools-hadk tar

我们强烈建议所有搬运工至少使用3.0.0.8 Platform SDK。 使用sdk-manage命令升级您的工具和目标，或重新创建（特别是从2.x升级到3.x时）。

查看您的版本：

PLATFORM_SDK $

# if no such file, you're on an old SDK version
cat /etc/os-release

更多保持你 SDK 最新的信息: https://sailfishos.org/wiki/SDK_Tips#SDK_Maintenance

4.3 设置Android构建环境

4.3.1 下载并解压 Ubuntu Chroot

为了保持构建的稳定性，我们在 Platform SDK 中使用 Ubuntu GNU / Linux chroot 环境来构建 Android 源代码树。

下面的命令可以下载并将 rootfs 解压到一个适当的位置：

PLATFORM_SDK $

TARBALL=ubuntu-trusty-20180613-android-rootfs.tar.bz2
curl -O https://releases.sailfishos.org/ubu/$TARBALL
UBUNTU_CHROOT=$PLATFORM_SDK_ROOT/sdks/ubuntu
sudo mkdir -p $UBUNTU_CHROOT
sudo tar --numeric-owner -xjf $TARBALL -C $UBUNTU_CHROOT

4.3.2 进入 Ubuntu Chroot

PLATFORM_SDK $

ubu-chroot -r $PLATFORM_SDK_ROOT/sdks/ubuntu

# 看这儿: 主机名解析可能会失败，该错误可以忽略
# 可以通过将主机名添加到  /etc/hosts 来手动修复

HABUILD_SDK $

# 现在您处于 HABUILD_SDK 环境中
# 想要离开时，只需输入`exit`或Ctrl + D，您将回到PLATFORM_SDK

第五章 建立 Android HAL

5.1 检查 Android 底包的源代码

我们的构建过程，基于Android源代码树，但是在需要的地方我们修改了一些项目，以应用一些可以使libhybris正确运行所需的补丁，并将 init.*.rc 文件中的内置动作和服务最简化。

确保已在Git配置中设置了名称和电子邮件地址：

HABUILD_SDK $

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

您还需要从AOSP源代码存储库安装 repo 命令，请参阅安装repo。

安装repo命令后，下面的一组命令将下载所需的项目，以构建在 Sailfish OS 硬件适应中使用的 Android 底包的修改部分。

可供移植的所有可用 Android 版本和版本都可以在此处查看：https：//github.com/mer-hybris/android/branches

选一个对硬件适配得最好的版本。

另外，您也可以修补自己选择的Android版本（例如CAF或AOSP或其他）。

Sailfish OS 移植的结果将是一个可安装的ZIP文件。 在将其部署到设备上之前，您必须先刷上相应版本的Android 底包，以便 Sailfish OS 可以重新使用其 Android HAL 共享对象。

如果您的刚开始的 ROM 与您的 Android基本版本或其版本不匹配，并且您应该将其保留在设备上，请寻找对它的MultiROM支持。 从v28版本开始，它支持启动Sailfish OS。

本移植指南以Nexus 5和CyanogenMod 11.0版本为例：

HABUILD_SDK $

sudo mkdir -p $ANDROID_ROOT
sudo chown -R $USER $ANDROID_ROOT
cd $ANDROID_ROOT
repo init -u git://github.com/mer-hybris/android.git -b hybris-11.0

5.2 设备存储库

本地 manifest 包含了适用于 Android 以及 mer-hybris 版本的设备特定的存储库。

如果您的设备已经被移植，那它的代码就已经被放置在了GitHub上，检查以下存储库：https://github.com/mer-hybris/local_manifests（选择要移植到的 hybris- * 的分支），并使用它的 $ DEVICE.xml 文件，而不需要在本章中创建新文件。

先建立目录：

HABUILD_SDK $

mkdir $ANDROID_ROOT/.repo/local_manifests

如果您正在创建新的移植，则必须自己创建本地的 manifest ，它至少包含两个存储库：一个用于内核，另一个用于设备配置。可以在LineageOS Wiki中找到，对于Nexus 5，链接是：https://wiki.lineageos.org/devices/hammerhead/build#initialize-the-lineageos-source-repository下面的本地 manifest 也需要指向正确的分支-要明确哪一个与默认 manifest 分支匹配 (stable/cm-11.0 in Nexus 5 case)。

把下面的内容加到 $ANDROID_ROOT/.repo/local_manifests/$DEVICE.xml 的后面：

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
	<project path="device/lge/hammerhead"
		name="CyanogenMod/android_device_lge_hammerhead"
		revision="stable/cm-11.0" />
	<project path="kernel/lge/hammerhead"
		name="CyanogenMod/android_kernel_lge_hammerhead"
		revision="stable/cm-11.0" />
</manifest>

花时间来同步一下整个源代码，这会花费很长一段时间：

HABUILD_SDK $

repo sync --fetch-submodules

同步后，源码树的预期磁盘使用量为 13 GB（从2015-09-09开始，hybris-11.0 分支）。
根据您的网络状况，这可能需要一些时间。 同时，您可以顺便熟悉一下本指南的其余部分。

5.3 配置挂载点信息

目前在Sailfish OS 中，udev 在 initrd 之后启动，这使得我们无法使用通用的分区名（与分区号无关）

然后，在 initrd 中，我们必须为 /boot 和 /data 分区指定硬编码的 /dev/mmcblkXpY 节点。

initrd 之后， systemd 需要挂载所有需要的其他分区（比如 /system , /firmware , /persist , /config, …），以使 HAL 层起作用。从* .fstab和init * .rc文件中读取所需的分区，在其中禁用它们，并创建相应的.mount单元 - 所有这些都由$ ANDROID_ROOT / rpm（droid-hal-device）完成。

不幸的是，由于 udev 启动较晚，故 systemd 无法识别 .mount 单位中的命名分区路径 ，即使你可以看见在 /dev/block/platform/*/by-name/或/dev/block/platform/ * / * /by - name 创建的节点.

要解决此问题，我们需要在每个设备的hybris / hybris-boot / fixup-mountpoints中的分区名称和数字之间创建一个映射，用于所有分区–这样，我们一定会覆盖所有分区，因为如果手动完成 通过fstab / rc文件查看时，有些文件可能不会被注意到。

要获得该映射，您应该刷新并引导Android基础，并在主机上执行adb shell，并在设备上执行以下命令：ls -l / dev / block / platform / * / by-name /。 万一屈服
没有结果尝试ls -l / dev / block / platform / * / * / by-name /在某些情况下，您也可以尝试ls -l / dev / block / bootdevice / by-name /。

未完待续。。。