Beroset: factored out this page from previous Creating an Asteroid app page

2026-01-14T21:00:26Z

factored out this page from previous Creating an Asteroid app page

New page

This page describes how to build an app using QtCreator rather than by using <code>bitbake</code>. As described in [[Creating an Asteroid app]], the preferred method for building an app is to set up and use <code>bitbake</code>. However, if you are a beginner and want to try a lower resource method for building, this page documents how to do so using QtCreator. The other relatively low resource method is to [[Build from the command line]].

= 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: <code>root</code> and <code>ceres</code> 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 <code>passwd</code> command to change the password. Remember each password because they will be needed later.

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

<pre>
PubkeyAuthentication yes
PermitEmptyPasswords no
</pre>

Once this is done, log out and then try to log back in via <code>ssh</code>. 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 <code>ssh-keygen</code>. 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:

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

==Install additional packages==
Two other software packages must be installed on the watch for QtCreator's "Test" to pass. They are <code>base64</code> and <code>rsync</code>. The <code>base64</code> software is part of the <code>coreutils</code> package and can be installed with this command as the <code>root</code> user on the watch:

<pre>
opkg install coreutils
</pre>

The <code>rsync</code> package is, at this time, not built as part of the packages, and so it must be built using <code>bitbake</code> as described [[https://wiki.asteroidos.org/index.php/Building_AsteroidOS]]. Instead of <code>bitbake asteroid-image</code>, one can just build the <code>rsync</code> package with <code>bitbake rsync</code>.

==Configure QtCreator for cross compilation==

Before running QtCreator you must run the previously mentioned script and set up the <code>CMAKE_PROGRAM_PATH</code>.

<pre>
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
</pre>

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

Now that you are in QtCreator go to <code>Edit</code> → <code>Preferences</code> → <code>Devices</code>

<ul>
<li>Add a new Remote Linux Device</li>
<li>Name it "AsteroidOS Watch"</li>
<li>Choose 192.168.2.15 as IP address</li>
<li>Choose 22 as the port</li>
<li>Use ceres as user</li>
</ul>
<br>
Under the <code>Kits</code> add a kit with the previously defined device:
<ul>
<li>Set <code>Device type</code> to Remote Linux Device</li>
<li>Set the <code>Device</code> to AsteroidOS Watch</li>
<li>Set the sysroot to <code>/usr/local/oecore-x86_64/sysroots/armv7vehf-neon-oe-linux-gnueabi/</code></li>
<li>In the CMake generator change the <code>Generator</code> to <code>Unix Makefiles</code></li>
<li>Change <code>Qt version</code> to <code>None</code></li>
<li>Change <code>C</code> compiler to <code><No compiler></code></li>
<li>Change <code>C++</code> compiler to <code><No compiler></code></li>
<li>Change <code>CMake Tool</code> to "AsteroidOS CMake" at <code>/usr/local/oecore-x86_64/sysroots/x86_64-oesdk-linux/usr/bin/cmake</code></li>
<li>Clear the <code>CMake Configuration</code> fields</li><li>Add a CMake variable: </li>
</ul><code>OE_QMAKE_PATH_EXTERNAL_HOST_BINS:STRING=%{Env:OE_QMAKE_PATH_HOST_BINS}</code>

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

= First app=

[https://github.com/AsteroidOS/asteroid-helloworld 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:

<pre>
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
</pre>

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 [http://doc.qt.io/qt-5/qml-tutorial.html official tutorial].

==== Translations ====
Within the AsteroidOS project, we use Qt Linguist and Weblate to enable [[Translating AsteroidOS]] and applications within it. If you're starting on "my-cool-project", you may want to add some language translations to it. This is done using the <code>lupdate</code> tool. Because Qt5 is nearing the end of support and Qt6 has been out for a while, the tool is named <code>lupdate-qt5</code> to differentiate between the two tools on most Linux distributions.

'''Example''': Let's say that you want to start with English, French, Spanish, German and Italian translations. You will have to create them before they can be translated. To do this, within your top level <code>my-cool-project</code> directory, execute the following command line code:

<pre>
for lang in en fr es de it
do
lupdate-qt5 -no-obsolete src/* i18n/*.h -ts i18n/my-cool-project.${lang}.ts
done
</pre>

This creates a <code>.ts</code> file for each of those language within the <code>i18n</code> directory.

Once they are created, you or others who know the languages may use [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist] to actually translate the strings. Note that AsteroidOS uses the [https://doc.qt.io/qt-5/linguist-id-based-i18n.html id based] translation mechanism which uses <code>qsTrId</code> rather than <code>qsTr</code>.

Qt and therefore AsteroidOS also supports national language variants, so if you want to create the Argentinian Spanish version or the Great Britain English version those would be named <code>es_AR</code> and <code>en_GB</code> respectively.

==== Updating language translation files ====
Once they are created, to update language translation files, and assuming you have all source files in <code>src</code> and translation files in <code>i18n</code> (which is short for "internationalization"), you can use this command to update the files.

<pre>
lupdate-qt5 -no-obsolete src/* i18n/*.h -ts i18n/*.ts
</pre>

==Deploy an app from QtCreator==

Open the project as described in the previous sections.
<ul>
<li>Click on the <code>Projects</code> button on the left sidebar</li>
<li>Under the <code>Build & Run</code> section click on the <code>Run</code> configuration. This opens all run settings</li>
<li>Scroll down to the <code>Run</code> settings</li>
</ul>

Change the following <code>Run</code> settings:
<ul>
<li>Set the <code>Run configuration</code> to <code>Custom Executable (on AsteroidOS Watch)</code></li>
<li>Under "Files to deploy" select "Override deployment data from build system"</li>
<li>Set the <code>Remote executable</code> to <code>asteroid-helloworld</code><br></li></ul>Under <code>Environment</code> select "Fetch Device Environment"
<ul>
<li>Change <code>XDG_RUNTIME_DIR</code> and set its value to <code>/run/user/1000</code>. So that the invoker works under the root user</li>
<li>Add <code>QT_QPA_PLATFORM</code> and set its value to <code>wayland</code></li>
<li>(Optional) Add <code>QT_WAYLAND_DISABLE_WINDOWDECORATION</code> with value <code>1</code>to make the app full screen and hide the titlebar</li>
</ul>
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:

<code>
QT_QPA_PLATFORM=wayland asteroid-stopwatch
</code>

Or more generally, call invoker directly:
<code>
QT_QPA_PLATFORM=wayland invoker --single-instance --type=qtcomponents-qt5 /usr/lib/asteroid-stopwatch.so
</code>

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

<code>
mcetool -D on
</code>

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 [[#Configure QtCreator for cross compilation | configuring QtCreator]]. The environment variables must all be set and then you must lauch <code>qtcreator</code> *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:

<code>
echo $CC
</code>

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

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 <code>source</code> (or <code>.</code> 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 <code><No compiler></code> as per the instructions above and may safely be ignored.

== file INSTALL cannot find ... .desktop==

This is probably the result of a missing <code>CMAKE_PROGRAM_PATH</code>. 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 <code>XDG_RUNTIME_DIR</code> is not set to <code>/run/user/1000</code> 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 <code>Build</code> from the menu, and then <code>Rescan project</code>. This will run CMake again, ignoring existing cached values and forcing the recreation of a Makefile.

Build with QtCreator - Revision history

Beroset: factored out this page from previous Creating an Asteroid app page