mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-14 00:53:49 +01:00
194 lines
7.4 KiB
Plaintext
194 lines
7.4 KiB
Plaintext
---
|
|
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](/build-system/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](/build-system/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:
|
|
|
|
|
|
|
|
- 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`)
|
|
|
|
|
|
|
|
## 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.
|
|
:::
|
|
|
|
|
|
|
|
- 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.
|
|
:::
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
|
|
|
- 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:
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
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)
|
|
:::
|
|
|
|
|
|
|
|
- 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
|
|
:::
|
|
|
|
|
|
|
|
- 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:
|
|
|
|
|
|
|
|
Congratulations! You just compiled your first RIOT application. To run RIOT
|
|
on real hardware, proceed with the next to sections.
|