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.

Currently only GNU/Linux is supported in this guide.

Installing the build prerequisites

  1. Install the needed build dependencies. On Ubuntu, the following is sufficient:
apt install git rustup ninja-build pkg-config libudev-dev clang gcc-arm-none-eabi

  1. Install the Rust installer rustup using the website's instructions or through your distribution package manager.

  2. Install the build system laze:

cargo install laze
  1. Install the debugging and flashing utility probe-rs:
cargo install --locked probe-rs-tools

  1. Clone the Ariel OS repository and cd into it.

  2. Install the Rust targets:

laze build install-toolchain

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.

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

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

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.