Getting started with Ariel OS

This guide is intended to get you started in about 5 minutes. It explains how to compile and run the hello-word example to verify your setup, and how to bootstrap a new application.

Installing the build prerequisites

Install the needed build dependencies.

Ubuntu (GNU/Linux)

apt install git ninja-build pkg-config libudev-dev clang gcc-arm-none-eabi gcc-riscv64-unknown-elf gcc curl make

Arch Linux

pacman -S git ninja pkgconf clang arm-none-eabi-gcc arm-none-eabi-newlib gcc curl make lib32-glibc

For RISC-V chips, the compiler can be installed via the riscv32-gnu-toolchain-elf-bin AUR package.

First, make sure to install the fakeroot and debugedit packages (part of the base-devel metapackage):

pacman -S fakeroot debugedit

riscv32-gnu-toolchain-elf-bin can be installed with an AUR helper, such as yay:

yay -S riscv32-gnu-toolchain-elf-bin

Or manually:

git clone https://aur.archlinux.org/riscv32-gnu-toolchain-elf-bin.git
cd riscv32-gnu-toolchain-elf-bin
makepkg -si

macOS (Apple Silicon)

brew install git ninja pkg-config llvm gcc curl

Install the Rust installer rustup using the website’s instructions.
Only for using ESP devices, install espup and related tools:
```
cargo install espup --locked
espup install
cargo install espflash@3.3.0 --locked
```
There is no need to actively source the ~/export-esp.sh file which espup produces: Ariel OS’s build system will consult that file when building for ESP.
Install the build system laze:
```
cargo install laze
```
Install the debugging and flashing utility probe-rs:
```
cargo install --locked probe-rs-tools
```
You might need to tweak permissions for non-admin access to connected devices. Please consult the probe-rs documentation for specifics.
Clone the Ariel OS repository and cd into it.
Install the Rust targets:
```
laze build install-toolchain
```
This invokes rustup to add all easy-to-install targets and components, and invokes espup if it is installed.

Running the `hello-world` example

To check that everything is installed correctly, the hello-word example can be compiled and run from the ariel-os directory. The following assumes you have your target board connected to your host computer.

Find the Ariel OS name of your supported board in the support matrix.

Note

The following assumes the Nordic nRF52840-DK, whose Ariel OS name is nrf52840dk. Replace that name with your board’s.

Then, from the ariel-os directory, compile and run the example, as follows:

laze -C examples/hello-world build -b nrf52840dk run

(This might fail if the flash is locked, click here for unlocking instructions.)

This might fail due to a locked chip, e.g., on most nRF52840-DK boards that are fresh from the factory. In that case, the above command throws an error that ends with something like this:

An operation could not be performed because it lacked the permission to do so: erase_all

The chip can be unlocked using this command:

laze -C examples/hello-world build -b nrf52840dk flash-erase-all

Terminal screencast of compiling and flashing the hello-world example

Tip

If you do not plan on working on Ariel OS itself, this repository is not needed anymore and can be deleted.

Starting an application project from a template repository

Applications are expected to be developed out-of-tree, outside of the ariel-os directory. This is made possible by laze’s imports feature.

To start a new application project, you can either clone the ariel-os-hello repository or, alternatively, use one of the cargo-generate templates.

Cloning `ariel-os-hello`

git clone https://github.com/ariel-os/ariel-os-hello

Using a `cargo-generate` project template

This requires installing cargo-generate, then a new application project can be created as follows:

cargo generate --git https://github.com/ariel-os/ariel-os-template --name <new-project-name>

Running the template example

To check your setup, the default application can be compiled and run as follows:

laze build -b nrf52840dk run

Important

The board name needs to be replaced with your board’s.

See the Build System page to learn more about laze and how to work with out-of-tree applications.

Keyboard shortcuts

Ariel OS manual