Debugging Applications: Difference between revisions

Latest revision as of 21:17, 14 January 2026

Debugging applications

This page describes some of the techniques commonly used to debug and modify software that runs on AsteroidOS. It assumes that the development host (that is, the machine on which you are writing and compiling your code) is running Linux as the operating system, since it is much simpler to write Linux code on Linux machines and makes the descriptions much shorter and easier. With that said, some Windows users have reported success in using [WSL].

Debug methods

Just as there are multiple ways to build software for AsteroidOS, there are also many techniques that can be useful to debug them and test them. A few are described below.

Native build

One simple method is to write the code so that it runs on the host machine and debug the application there. Then once it's working as you intend, you can compile it for the watch and make sure it also works as expected there.

However, most non-trivial programs for AsteroidOS will use specific watch features that are not generally available on host machines. One way to accommodate that is to write stub code for the watch-specific features and then when everything seems to be working with that, change to use the real code and compile for the watch.

Develop QML separately

The graphical user interface (GUI) code for AsteroidOS watch is generally written with [QML]. This code can be prototyped using the [qml] tool on the desktop. If it requires interaction with watch-specific things, as with the native build approach, these can be "faked" with stub code.

Another approach is to use asteroid-qmltester on the watch and copy the QML file to the watch for testing.

If you use [vim] one very handy and fast technique is to edit the QML file on the watch, but from your desktop, connected to the watch via ssh. For example, a command might be something like this:

vim scp://ceres@localhost:2222/Prototype.qml

That connects as the user ceres to the emulator which is running on port 2222 on the localhost. With a real watch, the command is similar:

vim scp://ceres@192.168.2.15/Prototype.qml

Then you can use asteroid-qmltester on the emulator or watch to see the result.

Other techniques

Other techniques could and should be described here such as:

using gdbserver on the watch
profiling QML code on the watch

@@ Line 1: / Line 1: @@
 == Debugging applications ==
 This page describes some of the techniques commonly used to debug and modify software that runs on AsteroidOS.  It assumes that the development host (that is, the machine on which you are writing and compiling your code) is running Linux as the operating system, since it is much simpler to write Linux code on Linux machines and makes the descriptions much shorter and easier.  With that said, some Windows users have reported success in using [[https://learn.microsoft.com/en-us/windows/wsl/install WSL]].
-=== Build methods ===
-If you have followed [[Creating an Asteroid app]] you will already have some idea of how to create an application that runs on AsteroidOS.  There are three ways that developers create applications:
-# Build from the command line
-# Build with QtCreator
-# Build with <code>devtool</code>
-The first two are described on the [[Creating an Asteroid app]] page.  The use of <code>devtool</code> is described on [[OpenEmbedded]].
-{| class="wikitable"
-|+ Build method table
-|-
-! Method !! Advantages !! Drawbacks
-|-
-| command line || simple, fast, easy to set up || doesn't always create <code>.ipk<\code> file
-|-
-| QtCreator || good for GUI development || difficult to set up, doesn't create <code>.ipk<\code> file
-|-
-| <code>devtool</code> || creates <code>.ipk<\code> file || complex to set up, slow
-|}
-Having a properly constructed <code>.ipk</code> file not only allows simplified installation on the watch, but also includes dependencies (other libraries on which the code might depend).  All of the <code>.ipk</code> files on our [https://release.asteroidos.org/nightlies/ipk/ nightly builds] are created using the OpenEmbedded tool <code>bitbake</code>.
-The command-line version build of <code>asteroid-helloworld</code> creates a simple installable <code>.ipk</code> file by adding build instructions for that directly to the [https://github.com/AsteroidOS/asteroid-helloworld/blob/a3908a7c7d13491b189ca4c0767c43ed24ce0271/CMakeLists.txt#L31C1-L45C15 CMakeLists.txt file].  This works as a temporary fix, but is generally '''not''' done for AsteroidOS projects because it would interfere with the way <code>bitbake</code> builds and because it does not automatically include dependencies, as mentioned above.
 === Debug methods ===