Creating an AsteroidOS app can be fun and rewarding. Creating an app requires the installation of the Software Development Kit (SDK) as described in Installing the SDK. The rest of this page assumes that you already have the SDK installed.

Building from the command line

Generally, to build a CMake project from the command line, use this:

export CMAKE_PROGRAM_PATH=/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/usr/bin/
source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi
cmake -B build
cmake --build build

If you're building for the Emulator, use this instead:

export CMAKE_PROGRAM_PATH=/usr/local/oecore-x86_64/sysroots/core2-32-oe-linux/usr/bin
source /usr/local/oecore-x86_64/environment-setup-core2-32-oe-linux
cmake -B build
cmake --build build

Example project

A example project, asteroid-helloworld is available as both an example and a template for new software. To fetch it from git and build it, use the following:

git clone https://github.com/AsteroidOS/asteroid-helloworld.git
cd asteroid-helloworld
export CMAKE_PROGRAM_PATH=/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/usr/bin/
source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi
cmake -B build -DCMAKE_INSTALL_PREFIX:PATH=/usr
cmake --build build --target package

If everything was successful, you should now have a new library named asteroid-helloworld.so in the build directory. You should also have an .ipk file in the build directory. If the watch is connected via USB to the host computer, you can copy this to the watch and then install it with:

scp build/asteroid-helloworld*.ipk root@192.168.2.15:.
ssh root@192.168.2.15 "opkg install asteroid-helloworld*.ipk"

Note that we specify the CMAKE_INSTALL_PREFIX in the commands above. This is to assure that the package is built to install the software in /usr/lib/ rather than /usr/local/lib/ which would otherwise be the default. The --target package instructs CMake to build a package the .ipk file in our case.

Once the software is installed, it should show up as the last item on the launcher page. Pressing the icon should show an orange background with the words "Hello World!" in white. You should make sure all of this works before going further with development.

Using QtCreator

QtCreator is an integrated development environment for making Qt QML applications. Previous versions of QtCreator allowed the use of passwords on the watch, but more recent versions require using SSH certificates. For this reason, the first thing to do is to prepare the watch to allow logging in using certificates.

Prepare the watch to use certificates

By default, there are two configured users on the watch: root and ceres both without passwords. The first step in deploying is to set up passwords for both users. This can be done by logging into the watch as each user and then running the passwd command to change the password. Remember each password because they will be needed later.

The next step is to modify the /etc/ssh/sshd_config file on the watch. The two settings to modify are:

PubkeyAuthentication yes
PermitEmptyPasswords no

Once this is done, log out and then try to log back in via ssh. You should be asked for the password. If so, then type in the password you just set and verify that things work.

The next step is to generate and copy a public key from your Linux computer to the watch. Although this can, in theory, be done from within QtCreator, doing so can be difficult to debug if things don't work perfectly. For that reason, this guide will only describe the command-line method.

First generate a key pair *on the host Linux computer* if there isn't already one there. This is typically done by running ssh-keygen. Different kinds of keys may be generated, but this example assumes an RSA key is generated. Once the key pair is created, you can deploy the public key to the watch:

ssh-copy-id -i ~/.ssh/id_rsa.pub ceres@192.168.2.15

Configure QtCreator for cross compilation

Before running QtCreator you must run the previously mentioned script and set up the CMAKE_PROGRAM_PATH.

export CMAKE_PROGRAM_PATH=/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/usr/bin/
source /usr/local/oecore-x86_64/environment-setup-armv7vehf-neon-oe-linux-gnueabi
qtcreator

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

Now that you are in QtCreator go to Edit → Preferences → Devices

Add a new Remote Linux Device
Name it "AsteroidOS Watch"
Choose 192.168.2.15 as IP address
Choose 22 as the port
Use ceres as user

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

Set Device type to Remote 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 Qt version to None
Change C compiler to <No compiler>
Change C++ compiler to <No compiler>
Change CMake Tool to "AsteroidOS CMake" at /usr/local/oecore-x86_64/sysroots/x86_64-oesdk-linux/usr/bin/cmake
Clear the CMake Configuration fields
Add a CMake variable:

OE_QMAKE_PATH_EXTERNAL_HOST_BINS:STRING=%{Env:OE_QMAKE_PATH_HOST_BINS}

Note that if these steps are not done *in this order*, QtCreator will not let you change both the C compiler and C++ compiler to <No compiler>. Specifically, setting Qt version to None must be done first.

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 https://github.com/AsteroidOS/asteroid-helloworld
cd asteroid-helloworld/
export CMAKE_PROGRAM_PATH=/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/usr/bin/
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)
Under "Files to deploy" select "Override deployment data from build system"
Set the Remote executable to asteroid-helloworld

Under Environment select "Fetch Device Environment"

Change XDG_RUNTIME_DIR and set its value to /run/user/1000. So that the invoker works under the root user
Add QT_QPA_PLATFORM and set its value to wayland
(Optional) Add QT_WAYLAND_DISABLE_WINDOWDECORATION with value 1to 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. Make sure you have the display on to be able to see the app. If you have "Tap-to-wake" turned on in the "Display" settings on the watch, tapping the display to wake up the screen before running the application should work.

Tips and tricks

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

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

Don't forget to turn it back off when you are done to avoid draining the battery.

Troubleshooting

The most common problems stem from not following these directions *exactly*. QtCreator helpfully tries to find compilers and set variables, but tends to set things up for the desktop as the target rather than AsteroidOS, so it often gets things wrong. The first step for troubleshooting with QtCreator is to go very carefully over each of the steps listed above and verify that they all match exactly.

Could not find a package configuration file provided by "ECM"

This is most often caused not having the environment variables set up as shown above under the topic of configuring QtCreator. The environment variables must all be set and then you must lauch qtcreator *in the same shell*. If you're not sure you've done this, an easy way to check is to try this command from the command line:

echo $CC

This should result in a line like this: arm-oe-linux-gnueabi-gcc -march=armv7ve -mfpu=neon -mfloat-abi=hard --sysroot=/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi

If instead you get an empty line or some other non-ARM compiler, you may have made an error. One common error is to run the script directly instead of running it using source (or . on some Linux distributions). Another common error that causes the error about not finding ECM is if, in the Kit, the system CMake is used instead of the one for the AsteroidOS SDK.

= warning: The project contains C++ source files, but the currently active kit has no C++ compiler. The code model will not be fully functional.

This is not really an error but a warning. It's the result of having correctly chosen <No compiler> as per the instructions above and may safely be ignored.

file INSTALL cannot find ... .desktop

This is probably the result of a missing CMAKE_PROGRAM_PATH. As mentioned above, this must be set in order for a script that generates the desktop file to be correctly found and uses.

Remote process crashed

One possibility is that your software has a bug, but another is that the XDG_RUNTIME_DIR is not set to /run/user/1000 as mentioned above.

"I fixed it but I get the same error!"

This most often happens when something was originally wrong with the configuration, but a CMake scan was made and a possibly faulty Makefile from an earlier attempt still exists. To fix this, choose Build from the menu, and then Rescan project. This will run CMake again, ignoring existing cached values and forcing the recreation of a Makefile.