OpenEmbedded (OE) is the build system used by AsteroidOS. It provides a way to easily maintain embedded Linux distributions. OE is also used by projects such as WebOS-Ports, SHR or Ångström. OpenEmbedded is supported by the Yocto project from the Linux Foundation and provides a rock-solid basis for AsteroidOS.
OpenEmbedded uses the
bitbake tool which is developed in Python to generate images (like
asteroid-image) from packages (like
asteroid-launcher-dev) built from recipes (ex:
asteroid-launcher_git.bb) provided in layers (ex:
Layers are git repositories containing a bunch of related recipes, example of layers include board support packages (BSPs) like meta-dory-hybris or
meta-rockchip which describe a way to support a new machine, but also UI layers like
meta-gnome which describe the building process of graphic components.
A recipe describes how to fetch, patch, configure, compile, install, package (in
.ipk) and test a piece of software. Bitbake handles all those operations and the dependencies between them and between recipes. In the end it can generate images or an SDK for multiple targets.
Contributing to the AsteroidOS’s OE architecture mostly consists in maintaining the meta-asteroid and meta-smartwatch repositories which contain the recipes related to AsteroidOS and the watches' BSPs.
In depth info can be found in the Yocto Project's manual
A Quick Tutorial
The rest of this description assumes that you have already read and followed the Building AsteroidOS instructions, and that you have built AsteroidOS for at least one platform (a particular watch or the emulator), and that you are familiar with
git and the Linux command line.
This tutorial will introduce you to the following topics:
- Changing an Existing Application You don't like how something behaves or want to fix an issue in an existing application? This will introduce you to the tooling used to allow you to make these changes.
- Adding a New Application Use the tooling to create a new application recipe and test it on a watch.
- Sharing your changes You've made changes on your local build of AsteroidOS. How do you share these changes? This will be explained in this part of the tutorial.
Changing an Existing Application
This will guide you step-by-step from the process of wanting to make a change to actually making that change and getting it running on your watch.
Let's say that you want to make a simple change to the flashlight app on the watch. Your favorite color is blue, so you want to change the flashlight screen's color to a blue color.
Since you have already run
bitbake asteroid-image you know that there are over 5000 tasks to create the image file that can be flashed to a watch. How do you figure out which of those 5000 tasks builds the flashlight application?
Two fundamental concepts within Yocto and bitbake are the layer and the recipe as mentioned above. Examine the layers in the AsteroidOS project:
bitbake-layers show-layers NOTE: Starting bitbake server... layer path priority ========================================================================== meta-qt5 /home/developer/asteroid/src/meta-qt5 7 meta /home/developer/asteroid/src/oe-core/meta 5 meta-asteroid /home/developer/asteroid/src/meta-asteroid 7 meta-asteroid-community /home/developer/asteroid/src/meta-asteroid-community 7 meta-oe /home/developer/asteroid/src/meta-openembedded/meta-oe 5 meta-multimedia /home/developer/asteroid/src/meta-openembedded/meta-multimedia 5 meta-gnome /home/developer/asteroid/src/meta-openembedded/meta-gnome 5 meta-networking /home/developer/asteroid/src/meta-openembedded/meta-networking 5 meta-android /home/developer/asteroid/src/meta-smartphone/meta-android 7 meta-python /home/developer/asteroid/src/meta-openembedded/meta-python 5 meta-filesystems /home/developer/asteroid/src/meta-openembedded/meta-filesystems 5 meta-anthias /home/developer/asteroid/src/meta-smartwatch/meta-anthias 7 meta-bass /home/developer/asteroid/src/meta-smartwatch/meta-bass 7 meta-beluga /home/developer/asteroid/src/meta-smartwatch/meta-beluga 7 meta-catfish /home/developer/asteroid/src/meta-smartwatch/meta-catfish 7 meta-dory /home/developer/asteroid/src/meta-smartwatch/meta-dory 7 meta-lenok /home/developer/asteroid/src/meta-smartwatch/meta-lenok 8 meta-mooneye /home/developer/asteroid/src/meta-smartwatch/meta-mooneye 7 meta-mtk6580 /home/developer/asteroid/src/meta-smartwatch/meta-mtk6580 7 meta-narwhal /home/developer/asteroid/src/meta-smartwatch/meta-narwhal 7 meta-ray /home/developer/asteroid/src/meta-smartwatch/meta-ray 7 meta-sawfish /home/developer/asteroid/src/meta-smartwatch/meta-sawfish 7 meta-skipjack /home/developer/asteroid/src/meta-smartwatch/meta-skipjack 6 meta-smelt /home/developer/asteroid/src/meta-smartwatch/meta-smelt 7 meta-sparrow /home/developer/asteroid/src/meta-smartwatch/meta-sparrow 7 meta-sprat /home/developer/asteroid/src/meta-smartwatch/meta-sprat 7 meta-sturgeon /home/developer/asteroid/src/meta-smartwatch/meta-sturgeon 7 meta-swift /home/developer/asteroid/src/meta-smartwatch/meta-swift 8 meta-tetra /home/developer/asteroid/src/meta-smartwatch/meta-tetra 7 meta-wren /home/developer/asteroid/src/meta-smartwatch/meta-wren 7
By convention, Yocto layers all begin with
meta. There are layers for individual pieces such as Qt, networking, Python, and filesystems. These are followed by the layers for each of the watch codenames. If you are looking for an AsteroidOS-specific application, you can probably guess that it's in the
meta-asteroid layer, but you can also ask the computer to search for you.
bitbake and its related tools were the only way to do things, but there is now a newer and much more convenient tool named
devtool. To search for a recipe with
flashlight in the name:
devtool search flashlight
After a minute or so,
devtool finds a single recipe:
asteroid-flashlight. You can now modify this recipe:
devtool modify asteroid-flashlight
The last two lines of output will be something like these:
INFO: Source tree extracted to /home/developer/asteroid/build/workspace/sources/asteroid-flashlight INFO: Recipe asteroid-flashlight now set up to build from /home/developer/asteroid/build/workspace/sources/asteroid-flashlight
Navigate into this directory, and find the relevant line in
src/main.qml and alter the color from white to light blue:
color: flashOn ? "lightblue" : "#66444444"
Save the altered source code and build this copy of the flashlight app:
devtool build asteroid-flashlight
After some time, the build will complete and you can test the application on a watch.
devtool deploy-target asteroid-flashlight email@example.com
Now the flashlight app will show a light blue screen. Reverting to the original version is very simple:
devtool undeploy-target asteroid-flashlight firstname.lastname@example.org
Adding a New Application
Let's say you have decided to create a new application. As described in Creating an Asteroid app page, the Asteroid-helloworld which can be used as the basis for your own new application can be cloned and then modified. So let's say you've done that and now you'd like to integrate the app into the Yocto and bitbake build system.
For these instructions, it is assumed that you have already built AsteroidOS for
sturgeon (or your preferred test platform). Let's say you have already cloned the
asteroid-helloworld into a directory named
~/tools/AsteroidOS/asteroid-helloworld/. You can very easily create a recipe for it with
devtool add hello ~/tools/AsteroidOS/asteroid-helloworld/
$ devtool add hello ~/tools/AsteroidOS/asteroid-helloworld/ NOTE: Starting bitbake server... NOTE: Starting bitbake server... INFO: Please add the following line for 'LICENSE' to a 'lib/recipetool/licenses.csv' and replace `Unknown` with the license: 84dcc94da3adb52b53ae4fa38fe49e5d,Unknown NOTE: Starting bitbake server... INFO: Recipe /home/developer/asteroid/build/workspace/recipes/hello/hello_git.bb has been automatically created; further editing may be required to make it fully functional
So the tool has created a recipe based on just the name we have given and the directory containing the source. Since it seems unsure about the license and suggests that further editing might be required, let's take its advice and edit the recipe. The simplest way to do that is again to use
devtool edit-recipe hello
This will open the recipe in an editor. It says that the license is unknown, so we change the line from
LICENSE = "Unknown" to
LICENSE = "GPL-3.0-only". Not that the
SRC_URI is set to point to a git repository. This is because
devtool is smart enough to figure out that even though you gave it a local directory, it discovered that the source was actually git and made the appropriate changes. We can now attempt to build.
devtool build hello
However this fails because we're still missing something. In this case, we're missing two things. First, instead of the
inherit cmake line, it should be
inherit cmake_qt5 and second, we need to add the following line just below that:
DEPENDS += "qml-asteroid asteroid-generate-desktop-native qttools-native qtdeclarative-native"
With those two small changes, we should now get a successful build.
As before, we can easily test on the watch:
devtool deploy-target hello email@example.com
This will automatically install all of the install targets from the
hello project onto the watch. Start the launcher on the watch and scroll to the end of your list of apps, and you should now see a "HELLO WORLD APP" at the end. Running it will show "Hello World!" on the screen.
Removing it from the watch is also the same as before:
devtool undeploy-target hello firstname.lastname@example.org
Sharing your changes
If you make a change to AsteroidOS software that you think might be useful to others, such as a bug fix or feature enhancement, there are several ways to share it, depending on what exactly is being changed.
- creating a recipe patch file
- creating a pull request for an AsteroidOS project
- creating an installable package (
Creating a recipe patch file
Many of the software packages that make up an AsteroidOS image are not unique to AsteroidOS. They may be general purpose tools such as
systemctl or watch-specific software from other open source repositories such as
mcetool. For these, there may be a need to introduce a patch just for AsteroidOS. To do so, first, within the appropriate
workspace directory where you made changes, use
git commit to commit the changes to the local repository. Once this is done, automatically create the patch. For our example, we could do that with this command:
devtool finish asteroid-flashlight meta-asteroid
This creates one patch for each new git commit and automatically updates the recipe file in the named layer (in this case,
meta-asteroid). (Note that this is just an example and would not really be appropriate for
asteroid-flashlight because this application is unique to AsteroidOS.) To see what was done, you can navigate to
asteroid/src/meta-asteroid and type
git diff. You will see that the patch file has been added to the recipe for
asteroid-flashlight. Also note that to ensure you don't lose any work,
devtool will not delete the directory tree in
workspace unless you specifically ask it to do so.
Create a pull request
For an AsteroidOS application, it may be more appropriate to create a *pull request*. To do that, we need to create a fork of the software we want to modify, create a branch, make the changes, commit and push the changes, and then create a pull request (PR). This guide doesn't describe all of these steps in detail, but describes how to use
git to create a PR.
Once the changes are made, as in the
asteroid-flashlight example above, you can simply use git to point to your own repository. Specifically, navigate to
asteroid/build/workspace/sources/asteroid-flashlight and use the command
git remote -v to see that the remote repository is the original source. Change it to point to your own repository with
git remote set-url origin MYCLONE, substituting your repository's URL for
MYCLONE. If you have already made local commits, you may wish to change the name of the branch from
devtool (which is what
devtool uses by default) to something meaningful to you before pushing the changes to your repository. Then create a PR from the new branch in the usual way.
Create an installable package
Chances are that your own Linux computer uses
.deb files with a package manager to allow simplified installation of software. AsteroidOS uses the
opkg package manager which uses
.ipk files. To create one from your modified software, here we need to use
bitbake rather than
Note that this typically creates four different
ipk files. We can take a look:
cd tmp-glibc/deploy/ipk/armv7vehf-neon/ ls asteroid-flashlight*
This returns the names of the four files:
asteroid-flashlight-dbg_+git999-r1_armv7vehf-neon.ipk asteroid-flashlight-dev_+git999-r1_armv7vehf-neon.ipk asteroid-flashlight_+git999-r1_armv7vehf-neon.ipk asteroid-flashlight-src_+git999-r1_armv7vehf-neon.ipk
We can ignore the
-src files and simply choose the one with the shortest name, which is the release version of the package. We can copy it to the watch:
scp asteroid-flashlight_+git999-r1_armv7vehf-neon.ipk email@example.com:.
Now we can SSH as root to the watch (
ssh firstname.lastname@example.org) and install the package:
opkg --force-reinstall install asteroid-flashlight_+git999-r1_armv7vehf-neon.ipk