Porting to a new device/Kernel package/Preparation
APKBUILD file
APKBUILD has nothing to do with Android's app format! |
APKBUILD
file is a script used to build a package. APKBUILDs for device-
and linux-
packages related to the device need to be edited before building as suggested by the following guide.
$ cd $(pmbootstrap config aports)/device/testing/device-wiki-example
$ cd $(pmbootstrap config aports)/device/testing/linux-wiki-example
If you are curious about APKBUILD variables and functions, you can look at pmbootstrap specific APKBUILD options and Alpine APKBUILD Reference.
Source code
Find the source code of the known working kernel fork. Try to find a widely used kernel if possible, for example from LineageOS. The kernel version is also important, as of writing (April 2020), the lowest kernel version number we have packaged is 3.0.x. It might be possible to get even older kernels running (with old GCC versions), but even if you get them to boot, you will likely run into problems down the road.
Once you have your kernel, adjust the # Source
section in the linux-wiki-example/APKBUILD
file.
Source section generated by default:
# Source
_repository="(CHANGEME!)"
_commit="ffffffffffffffffffffffffffffffffffffffff"
_config="config-$_flavor.$arch"
source="
$pkgname-$_commit.tar.gz::https://github.com/LineageOS/$_repository/archive/$_commit.tar.gz
You have to change _repository
and _commit
variables. _repository
is a name of repository, _commit
is a commit hash.
Commit hash is a unique identifier of a change in git repository and it may be found in different places depending on a platform where the kernel source is stored. In general, link to commit details contains full hash.
Example:
If your kernel is not in a LineageOS repository, you also have to change the URL in source
accordingly.
Example for https://github.com/jmrohwer/TF101-GNU-kernel :
# Source
_repository="TF101-GNU-kernel"
_commit="5ddd9654ec52599fbef71657ad2e03b3cdacee31"
_config="config-$_flavor.$arch"
source="
$pkgname-$_commit.tar.gz::https://github.com/jmrohwer/$_repository/archive/$_commit.tar.gz
If your kernel is only available as archive (zip, tarball, etc.), you can unpack it and use pmbootstrap build linux-wiki-example --src=/path/to/extracted/kernel/source
for now. Later on, when it's time to upstream your work into the official postmarketOS repositories so everybody can use it, talk to us so we can publish the kernel in a good place.
Do not fork the kernel and add patches there. There are already enough Linux kernel forks out there, and it's next to impossible to understand which kernel repository has which patches applied. Let's not make the situation worse with creating another fork with random patches on top just to make it compile with postmarketOS. Instead, point to the kernel you found. All postmarketOS specific patches should be applied as patch files in the same directory as the APKBUILD. How this is done exactly is described further below in the porting guide. When doing it like that, we avoid downloading the huge kernel sources every time a new patch is applied (remember that not everybody in the world has fast Internet connections), and it makes it much more transparent as the actual patches show up in code reviews.
Consider the reliability of the kernel source. If there is any chance that the source might disappear, a backup must be taken and used instead of the original source. See How to properly backup downstream kernels for instructions.
Kernel version
In the repository with the kernel source code, you will find a Makefile
. Open this file and adjust the pkgver
in the kernel APKBUILD
to the information from the VERSION
, PATCHLEVEL
and SUBLEVEL
variables (e.g. 3.4.0).
Defconfig
Next you will need to find the kernel configuration that is used to compile that kernel source for your device. Download it and save it as pmaports/device/testing/linux-wiki-example/config-wiki-example.armv7
(replace wiki-example
and armv7
).
$ wget https://github.com/LineageOS/lge-kernel-mako/raw/cm-14.1/arch/arm/configs/lineageos_mako_defconfig
$ mv lineageos_mako_defconfig pmaports/device/testing/linux-wiki-example/config-wiki-example.armv7
Download sources and update checksums
Use the checksum command. It will not only generate the checksums of all source files, but also download them in case they have not been downloaded yet. If this command fails, most likely the download URL is invalid and needs to be adjusted in the APKBUILD
again. Another cause could be, that the defconfig could not be found (e.g. because it was saved with a wrong file name). The actual download URL (with all variables replaced) and the download progress are visible in the log window.
$ pmbootstrap checksum linux-wiki-example