---
title: Setup Development Environment
description: Setting up a development environment for RIOT
---

import Contact from '@components/contact.astro';

<Contact />

### Choosing the Right Operating System

#### Linux (Recommended)
Most of the RIOT OS developers are using Linux on their development PCs, so you can expect the
most streamlined experience here. Generally, most Linux distributions are supported.

If you are new to Linux, we recommend using Ubuntu, as it is the most widely used distribution
and has the most extensive documentation and community support.

Some distributions, such as Fedora, do not provide the necessary packages for
cross compilation. In this case, it is recommended to use the
[RIOT Docker Container](/docs/guides/build-in-docker).

#### Windows
Windows is supported through Windows Subsystem for Linux (WSL).
The experience is not as streamlined as on Linux, but it is still possible to develop with RIOT.

:::note
Please follow the [installation guide for WSL](/getting-started/install-wsl) to set up your development environment.

Afterwards, you can follow the Ubuntu installation guide. The installation of the required software packages is the same for both Ubuntu and WSL.
:::

#### macOS
Native development on macOS machines is not officially supported.

What works well is using Linux in a virtual machine, but at much lower performance than running Linux natively.

We also offer Docker images that make it a bit easier to develop on macOS.

## Installing the required software packages

:::note
It is also possible to run RIOT in a Docker container.

This is especially useful if you want to avoid installing the required software packages on your host system. For more information, see the [Build in Docker](/docs/guides/build-in-docker) guide.
:::

Depending on the operation distribution you are using, the installation of the required software packages may vary.

##### Ubuntu

```bash title="Ubuntu command to install required packages"
    sudo apt install make gcc-multilib python3-serial wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang
```

#### Arch Linux

```bash title="Arch Linux command to install required packages"
    sudo pacman -S make gcc-multilib python-pyserial wget unzip git openocd gdb esptool podman-docker clang
```

This will show something like this depending on your distribution:

![Ubuntu terminal waiting for confirmation for installation](img/03-Install_Base_Packages-01.png)

- Confirm the installation by hitting the return-key
- The installation process will take some time
- Eventually the output will look like below (except for the `exit`)

![Ubuntu terminal after installation completed](img/03-Install_Base_Packages-02.png)

## Cloning the RIOT Repository and First Steps in the Terminal

:::note
Even if you subsequently work only via VS Code, do **NOT** skip this step.
You will still need a "clone" of the RIOT Repository to work with.
:::

![Cloning of the RIOT Repo in the Ubuntu terminal](img/05-First_Steps-00.png)

- Open the terminal.
- Type `git clone https://github.com/RIOT-OS/RIOT` and confirm with the return-key
- This may take some time. Eventually, it will print `done.` when it completed
- Type `cd RIOT/examples/hello-world` and confirm with the return-key to enter
  the folder `hello-world` example app in the RIOT repo
- Type `make` and confirm with the return key to build the app for the board
  `native`

:::tip
If you are having issues with missing libraries you can always also
use the docker container to build the app.
In this example you can type `BUILD_IN_DOCKER=1 make` to build the app in the docker container.
:::

:::note
The `native` board is a virtual board that will run an RIOT application as
regular Linux process. This can be useful for testing or during development.
The app should behave the same when run on real hardware.
:::

![The `hello-world` app running on the virtual `native` board](img/05-First_Steps-01.png)

- Now run the application by executing `make term`
- The output should look similar to the screenshot above
- You can close the terminal by:
    1. Press and hold the `Ctrl`-key
    2. With the `Ctrl`-key still held, press the `C`-key
    3. Release both keys

## Using VS Code for Development

![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-00.png)

- If not already open, open the terminal
- Confirm that the terminal is pointed to the folder `~/RIOT/examples/hello-world`
    - The blue part left of the prompt (the `$` sign in the terminal) shows
      the current working directory for the terminal
    - If the blue string is not `~/RIOT/examples/hello-world`, type
      `cd ~/RIOT/examples/hello-world` to enter that path
- Inside `~/RIOT/examples/hello-world` run the command `make compile-commands`
- The output should look like above

![Launching VS Code from Ubuntu](img/06-Use_VS_Code-01.png)

- Navigate back to `~/RIOT` using the command `cd ~/RIOT`
- run `code .` to launch VS Code
    - This will take a bit longer on the first launch
- Eventually, a VS Code Window should pop up that looks like this:

![VS Code as opened from WSL](img/06-Use_VS_Code-02.png)

1. Click on "Yes, I trust the authors"

- Now, use the tree view in the left and open the `examples` folder
- Open the `hello-world` folder inside the `examples` folder
- Open the `main.c` file in the `hello-world` folder within `examples`
- The file should open and look like this:

![VS Code asking to install C/C++ Extension](img/06-Use_VS_Code-03.png)

1. Click on the "Install" button when prompted to install the C/C++ Extension.

:::note
You can also install that extension via the extension marketplace if that pop up does not show up.
:::

:::danger
![VS Code asking to configure RIOT as CMake project](img/06-Use_VS_Code-04.png)

Do **NOT** configure RIOT as CMake project. VS Code will incorrectly detect
RIOT as CMake project, because it contains external packages that indeed are
using CMake.

1. Click on "Not now" to not configure RIOT as CMake project
2. Click on "Never" to never ask again whether RIOT should be configured as
   CMake project (not shown in screenshot)
:::

![IntelliSense showing that `RIOT_BOARD` is `"native"`](img/06-Use_VS_Code-05.png)

- Confirm that when hovering over `RIOT_BOARD` in the source code, IntelliSense
  shows that it expands to `"native"`.

:::note
IntelliSense depends on information how to compile the source code to work
correctly, which is provided in the file `compile_commands.json`. You can
regenerate this file by running `make compile-commands` in the app you are
working on.
:::

:::caution
Re-run `make compile-commands` when:
1. You create, delete or rename source files
2. You change the set of modules or packages used
3. You have updated the RIOT repository
4. You are switching the board to compile for
:::

![Compiling via the Terminal in VS Code](img/06-Use_VS_Code-06.png)

- Extend the message to be printed, e.g. by adding a `puts("...");` statement
  in the source code
- Save the modified source code (e.g. `Ctrl`+`S`)
- Open the integrated terminal by clicking on the terminal tab at the bottom
- Navigate to `~/RIOT/examples/hello-world` using `cd ~/RIOT/examples/hello-world`
- Run the `make` command to build the code
- Run make `make term` to launch the application
- The result should look like:

![Running the app in VS Code](img/06-Use_VS_Code-07.png)

Congratulations! You just compiled your first RIOT application. To run RIOT
on real hardware, proceed with the next to sections.
