Getting the Cross Compilation Toolchain

The app creation process of AsteroidOS needs a Software Development Kit generated by OpenEmbedded. You can either grab a prebuilt SDK for the nightlies here and install it on your system or you can build it yourself as follows:

Building the Cross Compilation Toolchain

Alternatively you can also build the toolchain from source. If you’ve already got an OpenEmbedded build directory via the Building AsteroidOS page, cd to that directory. Else, create one with:

Without Docker

git clone
cd asteroid/

Then, build the cross compilation toolchain with:

source ./ dory
bitbake meta-toolchain-qt5


Assuming you already prepared a docker build environment like in: Building AsteroidOS.

sudo docker rm -f asteroidos-toolchain ; sudo docker run --name asteroidos-toolchain -it -v /etc/passwd:/etc/passwd:ro -u "$(id -u):$(id -g)" -v "$HOME/.gitconfig:/$HOME/.gitconfig:ro" -v "$(pwd):/asteroid" asteroidos-toolchain bash -c "source ./ dory && bitbake meta-toolchain-qt5"

Install the SDK

If you downloaded a prebuilt SDK, run the downloaded script. If you followed the previous steps, this will have generated the same installation script in tmp-glibc/deploy/sdk/, you can run it as follows:


This script will install the cross-compiler and ARM libraries in /usr/local/oecore-x86_64 by default, along with a script that needs to be sourced before every build. If you want to build a simple project via the terminal, this can be done like that:

source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi
cmake -B build
cmake --build build

Configure QtCreator for cross compilation

Before running QtCreator you must run the previously mentioned script:

source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi

This can be done automatically by prepending source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi before #!/bin/sh in /usr/bin/

Now that you are in QtCreator go to ‘Tools->Options->Devices

  • Add a new Generic Linux Device.
  • Name it "AsteroidOS Watch".
  • Choose as IP address.
  • Use root as user.
  • Choose Password authentication and leave the password field empty.

Under the 'Kits' add a kit with the previously defined device:

  • Set Device type to Generic Linux Device.
  • Set the Device to AsteroidOS Watch.
  • Set the sysroot to /usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/.
  • In the CMake generator change the Generator to Unix Makefiles.
  • Change C compiler to <No compiler>.
  • Change C++ compiler to <No compiler>.
  • Change Qt version to None.
  • Change CMake Tool to System CMake at /usr/local/oecore-x86_64/usr/bin/cmake
  • Clear the CMake Configuration fields.

First app

Asteroid-helloworld can act as a cool QML demo app to make your first steps into AsteroidOS development easier. You can clone it, build it, install it and then modify it to follow your needs:

git clone
cd asteroid-helloworld/
source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi
qtcreator CMakeLists.txt

Try to build and deploy the app. If it wasn’t already installed, a new icon should have already appeared on asteroid-launcher.

You can start by modifying occurrences of “asteroid-helloworld” to your app’s name. Then you can change the *.desktop file which describes the icon on the apps launcher. Then modify main.qml to describe your UI. To get started with QML development you can read the official tutorial.

Deploy an app from QtCreator

Open the project as described in the previous sections.

  • Click on the Projects button on the left sidebar.
  • Under the Build & Run section click on the Run configuration. This opens all run settings.
  • Scroll down to the Run settings.

Change the following 'Run' settings:

  • Set the Run configuration to Custom Executable (on AsteroidOS Watch).
  • Set the Remote executable to invoker. Add the --single-instance --type=qtcomponents-qt5 /usr/local/bin/asteroid-helloworld command line arguments.

Change the following 'Environment' variables:

  • Add XDG_RUNTIME_DIR and set its value to /run/user/1000. So that the invoker works under the root user.
  • (Optional) Add QT_WAYLAND_DISABLE_WINDOWDECORATION with value 1. To make the app full screen and hide the titlebar.

Your app should now be able to run from the application when you click the start button in the bottom left sidebar.

Tips and tricks

If you want to start your app from the command line, open a shell with SSH, connect to ceres and use invoker:

invoker --type=qtcomponents-qt5 /usr/bin/asteroid-stopwatch

If you want to disable screen locking for easier development you can enable the demo mode of mce as root with:

mcetool -D on