Debugging Applications - Revision history

Beroset: /* Debugging applications */ moved build method tables to Building an Asteroid app page

2026-01-14T21:17:17Z

Debugging applications: moved build method tables to Building an Asteroid app page

@@ 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]].
 === Debug methods ===

Mirkokral: Fix some tags

2025-03-05T17:56:17Z

Fix some tags

← Older revision		Revision as of 17:56, 5 March 2025
Line 15:		Line 15:
	! Method !! Advantages !! Drawbacks		! Method !! Advantages !! Drawbacks
	\|-		\|-
	\| command line \|\| simple, fast, easy to set up \|\| doesn't always create <code>.ipk<\code> file		\| 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		\| 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		\| <code>devtool</code> \|\| creates <code>.ipk</code> file \|\| complex to set up, slow
	\|}		\|}

Beroset: added a lot of text on practical tips for writing applications

2025-02-23T22:12:21Z

added a lot of text on practical tips for writing applications

New page

== 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 ===
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 [[https://doc.qt.io/qt-5/qmlapplications.html QML]]. This code can be prototyped using the [[https://doc.qt.io/qt-5/qtquick-qml-runtime.html 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 [[Applications#asteroid-qmltester|asteroid-qmltester]] on the watch and copy the QML file to the watch for testing.

If you use [[https://www.vim.org/ 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 <code>ssh</code>. For example, a command might be something like this:

<pre>
vim scp://ceres@localhost:2222/Prototype.qml
</pre>

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

<pre>
vim scp://ceres@192.168.2.15/Prototype.qml
</pre>

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

==== Other techniques ====
Other techniques could and should be described here such as:

# using <code>gdbserver</code> on the watch
# profiling QML code on the watch