Beroset: /* Tips and tricks */ added section on examining an ipk file and added header to prev section

2026-01-22T15:02:12Z

Tips and tricks: added section on examining an ipk file and added header to prev section

← Older revision		Revision as of 15:02, 22 January 2026
Line 76:		Line 76:
	</pre>		</pre>
	=Tips and tricks=		=Tips and tricks=
			==Running your app==
	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:		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:

Line 95:		Line 95:

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

			==Examining an .ipk file==
			On systems that have it, one can use <code>opkg-cl</code> or <code>ipkg-deb</code> to examine, extract or modify .ipk files. Without those, one can simply use <code>ar</code> and <code>tar</code>.
			Examples:
			<pre>
			ar t path/to/package.ipk # show members
			ar x path/to/package.ipk control.tar.gz data.tar.gz
			tar --zstd -tf data.tar.zst # list files from package payload
			tar --zstd -xf data.tar.zst -C /tmp/pkg-extract # extract payload
			</pre>

			We can also use one-liners to manipulate just the part of the .ipk file that contains data files (the package payload):

			<pre>
			ar p path/to/package.ipk data.tar.zst \| tar -tv --zstd # show data files
			ar p path/to/package.ipk data.tar.zst \| tar -xv --zstd # extract data files
			</pre>

	== Debugging ==		== Debugging ==
	Debugging is described in detail in [[Debugging Applications]]		Debugging is described in detail in [[Debugging Applications]]

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

2026-01-14T21:06:06Z

factored out this page from previous Creating an Asteroid app page

New page

This page describes how to build an app from the command line other 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 from the command line. The other relatively low resource method is to [[Build with QtCreator]].

== Prerequisites ==
To build an app from the command line using this method you should:
# Have the [[Installing the SDK|SDK installed]]
# Be familiar with CMake and C++

It is technically possible, but not generally recommended to create new AsteroidOS applications in languages other than C++ and with build tools other than CMake.

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

<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
cmake -B build
cmake --build build
</pre>

If you're building for the [[Emulator]], use this instead:
<pre>
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
</pre>

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

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

If everything was successful, you should now have a new library named <code>asteroid-helloworld.so</code> in the <code>build</code> directory. You should also have an <code>.ipk</code> 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:

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

Note that we specify the <code>CMAKE_INSTALL_PREFIX</code> in the commands above. This is to assure that the package is built to install the software in <code>/usr/lib/</code> rather than <code>/usr/local/lib/</code> which would otherwise be the default. The <code>--target package</code> instructs CMake to build a package the <code>.ipk</code> 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.

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>
=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.

== Debugging ==
Debugging is described in detail in [[Debugging Applications]]

Build from the command line - Revision history

Beroset: /* Tips and tricks */ added section on examining an ipk file and added header to prev section

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