Building AsteroidOS

If you decide to compile AsteroidOS from source be aware that it’s a simple process but requires a lot of disk space (potentially more than 100GB) and the first build might take you a lot of time (hours). Report any problem to the issue tracker:

Video showing the build process

General information

You might want to build AsteroidOS in a container engine such as Docker or podman because you'll get a clean build environment that works no matter what kinds of package repositories or package versions you have installed or how outdated your Linux distribution is or which Linux distribution you're using in the first place.

Another advantage of Docker specifically is that it should also work on Windows and OS X. (However, this has not been tested yet!)

Using containers also allows you to easily roll back. Without a container, if you decided to delete the AsteroidOS repository and uninstall the prerequisite software packages from your computer, you will potentially remove packages that you had installed before and might actually still need. With a container, simply deleting the container image has no other effect on the host computer.

Clone the repository

Clone the main repository using the following command:

git clone https://github.com/AsteroidOS/asteroid.git

If you haven't set a global git name and email yet, adapt the following git config commands to your information. (This is only required to clone some git repositories when building.)

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Before you continue to Build without containers or Build with containers, make sure you're in the asteroid directory:

cd asteroid/

Build without containers

Downloading

Install the prerequisites:

Distribution prerequisite installation

Distro	Command
Ubuntu	apt-get install git build-essential chrpath cpio diffstat gawk liblz4-tool python3 shared-mime-info texinfo wget zstd
Fedora	dnf install chrpath diffstat g++ lz4 perl perl-bignum python3-pip rpcgen socat texinfo
Arch	pacman -Sy base-devel chrpath cpio diffstat gawk inetutils lz4 python3 rpcsvc-proto shared-mime-info texinfo wget zstd
Alpine	apk add binutils chrpath gcc g++ gawk gcc lz4 make patch perl rpcgen Note: Alpine Linux does not contain diffstat in its repositories, thus you have to build it yourself from source.

This repository basically only contains a shell script that populates src/ with OpenEmbedded and the appropriate Asteroid layers. Then, it setups the environment for a bitbake build. The following command will setup a build for dory (the LG G Watch) but you can also build an image for other watches by using the corresponding codename. (Codenames can be found on the Watches page.)

source ./prepare-build.sh dory # Be careful that this script must be sourced and not only ran

If the environment has been correctly setup, you should now be in the build subdirectory.

Building

Once the environment is prepared, you can simply trigger a build with the following command:

bitbake asteroid-image

Notes: 1) The build process requires roughly 2GB memory per thread. It might be necessary to limit the number of threads. This can be done by prepending BB_NUMBER_THREADS=n to the build command. Or by adding BB_NUMBER_THREADS = "n" to build/conf/local.conf. Where n is the amount of threads. 2) Bitbake is a powerful tool that can also build single packages (e.g: bitbake strace) or Building the SDK for example. Refer to its documentation for more details.

If this step was successful, you can proceed to the Installing section below.

Updating the Sources

You can update the AsteroidOS sources with the following command:

source ./prepare-build.sh update

Build with containers

These instructions have been tested on Ubuntu 19.04 (with Docker) and Fedora 34 (with podman), but should also be applicable to Debian Sid (at least at the time of writing). For other distributions the dependencies may have different names and you may have to install additional ones.

From a user's point of view, Docker and podman are quite similar and accept almost all of the exact same commands, but there are some difference. The most significant differences for building Asteroid are that podman does not use a daemon and can be run "rootless" (that is, as a non-root user). This makes some things a bit easier, but either can be used.

Setup

Remove the Docker container called asteroidos-toolchain if it already exists:

sudo docker rm -f asteroidos-toolchain

or

podman rm -f asteroidos-toolchain

Build a container image called asteroidos-toolchain from the given Dockerfile:

sudo docker build --tag asteroidos-toolchain .

or

podman build --tag asteroidos-toolchain .

Building the software

Now that the container with the toolchain software has been created, we can use this to build AsteroidOS. All of the tools are contained and run within the container, but we use a shared volume, essentially some drive space that both the host computer and the container can read and write, for actually creating the AsteroidOS image files.

In this example, we will build AsteroidOS for dory(the LG G Watch). To build for a different watch than the LG G Watch, use its corresponding codename instead of dory when executing the docker run ... command. You can find the codenames for the supported watches on the Watches page.

Assuming that you have carefully followed the instructions so far and are in the asteroid directory, you can now build the software.

Run this as a non root user:

sudo docker run \
  --rm \
  -it \
  -v /etc/passwd:/etc/passwd:ro \
  -u "$(id -u):$(id -g)" \
  -v "$HOME/.gitconfig:/$HOME/.gitconfig:ro" \
  -v "$(pwd):/asteroid" asteroidos-toolchain \
  bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"

or

podman run \
  --rm \
  -it \
  -v  "$(pwd)":/asteroid:z \
  --userns keep-id asteroidos-toolchain \
  bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"

The files created during the build are placed in the current directory; more specifically, the source files are placed in a src subdirectory and build artefacts, including the final binary images are placed in the build subdirectory.

Here is a detailed explanation of the Docker command above:

• sudo docker run Runs a container image
• --rm Cleans up after the command is run by removing temporary container storage
• -it Attaches the terminal to the container so that we can see the output. Otherwise it would run blindly in the background.
• -u "$(id -u):$(id -g)" Ensures that the current user id and group id from the host is used on files inside the container to avoid permission issues.
• -v /etc/passwd:/etc/passwd Ensures that the user ids and groups from the host are also available in the Docker container. (Otherwise the -u and -g would be useless.)
• /etc/passwd Contains the user names and their ids.
• "$HOME/.gitconfig:/$HOME/.gitconfig" Share your user's git config with the container.
• -v "$(pwd):/asteroid" Mount the current directory (which is your asteroid git repo clone) into the container.
• bash -c "source ./prepare-build.sh dory && bitbake asteroid-image" This is the command to be executed inside of the container with "dory" being the codename of your watch.

Here is a detailed explanation of the podman version of the command above:

• podman run Runs a container image
• --rm Cleans up after the command is run by removing temporary container storage
• -it Attaches the terminal to the container so that we can see the output. Otherwise it would run blindly in the background.
• -v "$(pwd)":/asteroid:z Mount the current directory (which is your asteroid git repo clone) into the container. The :z tells SELinux, if it's running, to allow multiple containers to share this mount.
• --userns keep-id Run as the current user inside the container
• bash -c "source ./prepare-build.sh dory && bitbake asteroid-image" This is the command to be executed inside of the container with dory being the codename of your watch.

If this step was successful, you can proceed to Installing below.

Installing

After a while, whether you build with or without containers, the generated image should be available in build/tmp-glibc/deploy/images/dory/ (for dory -- for other watches, the image files are in the corresponding code word directory.)

Install AsteroidOS using your usual device's instructions, which you can find linked from the Watches page.