View source for Building AsteroidOS

[[Category:Developers]]
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 [https://github.com/AsteroidOS/asteroid/issues issue tracker]:


[https://asteroidos.org/asteroid.mp4 Video showing the build process]

= General information =

You might want to build AsteroidOS in a ''container engine'' such as [https://www.docker.com/ Docker] or [https://podman.io/ 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:

<pre>
git clone https://github.com/AsteroidOS/asteroid.git
</pre>

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

<pre>
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
</pre>

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

<pre>
cd asteroid/
</pre>

= Build without containers =

== Downloading ==

Install the prerequisites:


{| class="wikitable"
|+ Distribution prerequisite installation
|-
! Distro !! Command
|-
| Ubuntu || <code>apt-get install git build-essential chrpath cpio diffstat gawk liblz4-tool python3 shared-mime-info texinfo wget zstd </code>
|-
| Fedora || <code>dnf install chrpath diffstat g++ lz4 perl perl-bignum python3-pip rpcgen socat texinfo patch</code>
|-
| Arch || <code>pacman -Sy base-devel chrpath cpio diffstat gawk inetutils lz4 python3 rpcsvc-proto shared-mime-info texinfo wget zstd</code>
|-
| Alpine || <code>apk add binutils chrpath gcc g++ gawk gcc lz4 make patch perl rpcgen</code> <br>Note: Alpine Linux does not contain diffstat in its repositories, thus you have to [https://github.com/asottile-archive/diffstat build it yourself from source].
|}

This repository basically only contains a shell script that populates <code>src/</code> with OpenEmbedded and the appropriate Asteroid layers. Then, it setups the environment for a bitbake build. The following command will setup a build for <code>dory</code> (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 [https://asteroidos.org/watches/ Watches page].)

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

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

== Building ==

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

<pre>
bitbake asteroid-image
</pre>
''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 <code>BB_NUMBER_THREADS=n</code> to the build command. Or by adding <code>BB_NUMBER_THREADS = "n"</code> to <code>build/conf/local.conf</code>. Where <code>n</code> is the amount of threads.
2) Bitbake is a powerful tool that can also build single packages (e.g: <code>bitbake strace</code>) or  [[Creating an Asteroid app#Building the Cross Compilation Toolchain|Building the SDK]] for example. Refer to its documentation for more details.

If this step was successful, you can proceed to the [[#Installing|Installing]] section below.

== Updating the Sources ==

You can update the AsteroidOS sources with the following command:

<pre>
source ./prepare-build.sh update
</pre>


= Build with containers =

These instructions have been tested on Ubuntu 19.04 (with Docker) and Fedora 41 (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 <code>asteroidos-toolchain</code> if it already exists:

<pre>
sudo docker rm -f asteroidos-toolchain
</pre>
or
<pre>
podman rm -f asteroidos-toolchain
</pre>

Build a container image called <code>asteroidos-toolchain</code> from the given Dockerfile:

<pre>
sudo docker build --tag asteroidos-toolchain .
</pre>
or
<pre>
podman build --tag asteroidos-toolchain .
</pre>

== 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 <code>dory</code>(the LG G Watch).  To build for a different watch than the LG G Watch, use its corresponding codename instead of <code>dory</code> when executing the <code>docker run ...</code> command.  You can find the codenames for the supported watches on the [https://asteroidos.org/watches/ Watches page].



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

'''Run this as a non root user''':

<pre>
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"
</pre>
or
<pre>
podman run \
  --rm \
  -it \
  -v  "$(pwd)":/asteroid:Z \
  --userns keep-id asteroidos-toolchain \
  bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"
</pre>

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

Here is a detailed explanation of the Docker command above:

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

*<code>podman run</code> Runs a container image
*<code>--rm</code> Cleans up after the command is run by removing temporary container storage
*<code>-it</code> Attaches the terminal to the container so that we can see the output. Otherwise it would run blindly in the background.
*<code>-v "$(pwd)":/asteroid:Z</code> Mount the current directory (which is your asteroid git repo clone) into the container. The <code>:Z</code> tells SELinux, if it's running that this container has ''exclusive access'' to this mount.  If <code>:z</code> is used instead, it tells SELinux, if it's running, to allow multiple containers to share this mount.  Either can be used, but the exclusive access flag avoids the need to re-apply security labels to all files which can take significant time when the container starts.
*<code>--userns keep-id</code> Run as the current user inside the container
*<code>bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"</code>  This is the command to be executed inside of the container with <code>dory</code> being the codename of your watch.

If this step was successful, you can proceed to [[#Installing|Installing]] below.

= Installing =

After a while, whether you build with or without containers, the generated image should be available in <code>build/tmp/deploy/images/dory/</code> (for <code>dory</code> -- 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 [https://asteroidos.org/watches/ Watches page].