KaiOS

This page contains information about the Mozilla/KaiOS collaboration including building instructions, links to the code and various other resources. The scope of the project is to modernize the old Boot2Gecko codebase to run atop a modern Gecko so that it can be used by KaiOS as a basis for their future phones.

Contents

Building

There's two ways to build the project: a full emulator build or a stand-alone Gecko build. Generally speaking you won't need the full emulator build unless you're doing work specifically on it.

Building a stand-alone Gecko

Clone the kaios project branch:

hg clone https://hg.mozilla.org/projects/kaios

Bootstrap your build environment via mach

export LOCAL_NDK_BASE_URL='ftp://ftp.kaiostech.com/ndk/android-ndk' ./mach bootstrap --application-choice='Boot2Gecko'

Add a suitable mozconfig file, you can use the following one for the time being

# Build Boot2Gecko
ac_add_options --enable-application=b2g
ac_add_options --with-app-basename=b2g

# Android
ac_add_options --with-android-version=29
ac_add_options --target=x86_64-linux-android

# Compiler options
ac_add_options --with-android-ndk="$HOME/.mozbuild/android-ndk-r20b-canary"

# B2G-specific options
ac_add_options --with-gonk-gfx
ac_add_options --with-gonk="$HOME/.mozbuild/b2g-sysroot/"
ac_add_options --enable-b2g-camera
ac_add_options --enable-b2g-ril
ac_add_options --enable-b2g-fm
ac_add_options --enable-forkserver

# Only for x86-64
ac_add_options --enable-wasm-simd

# Sandbox & profiler are not supported yet
ac_add_options --disable-profiling
ac_add_options --disable-sandbox

# Compiler/Linker options

# Since we use lld we need to disable elf-hack
ac_add_options --enable-linker=lld
ac_add_options --disable-elf-hack

Build as usual with ./mach build

Building the emulator

This involves downloading the entire AOSP tree and building an Android emulator from it, including the Gecko bits. It's a long and slow process and it requires at least 120GB of free space on your disk.

Clone the B2G tree

git clone https://github.com/kaiostech/B2G.git

Configure the tree for building the x86-64 emulator. This step will download all the AOSP sources required for the build which are 10s of GB so be patient

REPO_INIT_FLAGS="--depth=1" ./config.sh emulator-10-x86_64

Setup your environment to fetch the custom NDK

export LOCAL_NDK_BASE_URL='ftp://ftp.kaiostech.com/ndk/android-ndk'

Install Gecko dependencies

cd gecko && ./mach bootstrap --application-choice Boot2Gecko

Build by invoking the build.sh script in the top-level directory. Depending on your machine this step can take anywhere from 30 minutes to several hours

./build.sh

Running the emulator

If you've built the emulator yourself you can launch it from the root *B2G* folder. First source the setup for your build, you will have to execute this step only once before launching the emulator

source setup.sh

Once the environment is primed launch the emulator with the following command

emulator -writable-system -selinux permissive

Building the desktop version

The desktop version can be used to work on the front-end and debug other non-platform-specific parts of Gecko. Building it is fairly simple:

Clone the kaios project branch:

hg clone https://hg.mozilla.org/projects/kaios

Bootstrap your build environment via mach

./mach bootstrap --application-choice browser

Build using the mozconfig-b2g-desktop configuration (feel free to tweak it to suite your purposes):

env MOZCONFIG=mozconfig-b2g-desktop ./mach build

Run your build using the same mozconfig, the very simple default homescreen will show up:

env MOZCONFIG=mozconfig-b2g-desktop ./mach run

Development

Adding new dependencies to the sysroot

The Android-specific dependencies used in the build are taken from a sysroot generated via the create-b2g-sysroot.sh script. Dependencies are split in multiple lists which include libraries, headers and generated headers. Depending on what dependency you want to add follow the steps below:

Adding a new system library (lib<name>.so)

  • Add the library the full path to the library to the list of libraries and shared objects, please keep the list sorted
  • Add the library name to the OS_LIBS variable in the appropriate moz.build file. Note that you don't need to specify the lib prefix nor the .so extension, just the library name.

Adding a new Android shared object (<name>@<version>.so format)

Adding a new set of headers

  • Find the path to the headers you want to include and note their relative path. If your source is including B2G/foo/bar/baz.h via #include <bar/baz.h> then the path you will want to add the foo path.
  • Add the path you noted above to the appropriate list of headers:
    • System includes go here
    • Generated AIDL headers go here (you can recognize them by a #define AIDL_... definition. AIDL headers sometimes have the target architecture in their path so make sure you don't hard-code it in the script but use the appropriate variable instead to avoid breaking other targets
    • Generated HIDL headers go here (you can recognize them by a #define HIDL_... definition