View source for 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.

= 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:
<pre>hg clone https://hg.mozilla.org/projects/kaios</pre>
Bootstrap your build environment via mach
<pre>export LOCAL_NDK_BASE_URL='ftp://ftp.kaiostech.com/ndk/android-ndk' ./mach bootstrap --application-choice='Boot2Gecko'</pre>
Add a suitable mozconfig file, you can use the following one for the time being
<pre>
# 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
</pre>
Build as usual with <code>./mach build</code>

== 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
<pre>git clone https://github.com/kaiostech/B2G.git</pre>
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
<pre>REPO_INIT_FLAGS="--depth=1" ./config.sh emulator-10-x86_64</pre>
Setup your environment to fetch the custom NDK
<pre>export LOCAL_NDK_BASE_URL='ftp://ftp.kaiostech.com/ndk/android-ndk'</pre>
Install Gecko dependencies
<pre>cd gecko && ./mach bootstrap --application-choice Boot2Gecko</pre>
Build by invoking the <code>build.sh</code> script in the top-level directory. Depending on your machine this step can take anywhere from 30 minutes to several hours
<pre>./build.sh</pre>

=== 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
<pre>
source setup.sh
</pre>
Once the environment is primed launch the emulator with the following command
<pre>
emulator -writable-system -selinux permissive
</pre>

== 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:
<pre>hg clone https://hg.mozilla.org/projects/kaios</pre>
Bootstrap your build environment via mach
<pre>./mach bootstrap --application-choice browser</pre>
Build using the <code>mozconfig-b2g-desktop</code> configuration (feel free to tweak it to suite your purposes):
<pre>env MOZCONFIG=mozconfig-b2g-desktop ./mach build</pre>
Run your build using the same mozconfig, the very simple default homescreen will show up:
<pre>env MOZCONFIG=mozconfig-b2g-desktop ./mach run</pre>

= Development =

== Adding new dependencies to the sysroot ==
The Android-specific dependencies used in the build are taken from a sysroot generated via the [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh 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 [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh#69-121 list of libraries and shared objects], please keep the list sorted
* Add the library name to the [https://searchfox.org/kaios/rev/66d140e3f973a2257d45c006afd1a30f76844b1e/toolkit/library/moz.build#107-133 <code>OS_LIBS</code>] 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) ===

* Add the library the full path to the shared object to the [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh#69-121 list of libraries and shared objects], please keep the list sorted
* Add the object name to the [https://searchfox.org/kaios/rev/66d140e3f973a2257d45c006afd1a30f76844b1e/toolkit/library/moz.build#134-158 AOSPSharedObjects template] without the '''.so''' extension

=== 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 <code>B2G/foo/bar/baz.h</code> via <code>#include <bar/baz.h></code> then the path you will want to add the <code>foo</code> path.
* Add the path you noted above to the appropriate list of headers:
** System includes go [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh#125-164 here]
** Generated AIDL headers go [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh#168-178 here] (you can recognize them by a <code>#define AIDL_...</code> 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 [https://searchfox.org/kaios/source/taskcluster/scripts/misc/create-b2g-sysroot.sh#182-213 here] (you can recognize them by a <code>#define HIDL_...</code> definition