Skip to content

Developer Environment

The infamous problem of "it works on my machine" can be (mostly) solved by using dev containers. A dev container is a consistent environment for building and running software. Most are run on Docker, a light weight virtualisation engine which allows us to run a Linux system on top of our own with minimal overhead. This allows us to run and build software meant for specific environments on our own machine without needing to match the exact version of dependencies and change our hosts configuration.

OS Support and Linux🔗

Linux is a open source operating system and is favoured by developers (and many home users) for the control it gives the user over their computer. This is one of the many reasons that makes Linux favoured in robotics applications. Specific to us is the distribution of Linux known as Ubuntu 22.04, which is the only version of Linux that ROS2 Humble officially supports. It is also the only distribution that Gazebo officially supports, and the PX4 development toolchain does not support native Windows.

A distribution of Linux is an operating system that uses the Linux kernel, different distribution will package software differently, release updates differently, use different init systems, come with different default software, and much more.

This guide recommends the native installation of Ubuntu 22.04 for development as this is a relatively user friendly distribution and will help you get familiar with the developer environment in which we work.

These tutorials will assume you are using Linux, WSL and macOS notes will be provided when applicable. (PRs welcome)

Note that once you get the container setup, your host OS will be largely irrelevant.

WSL2

Docker on Windows via WSL2 can be used, however Gazebo (the simulator) seems to have problems with using the GPU. If you'd like to try here are some resources that may help:
https://learn.microsoft.com/en-us/windows/ai/directml/gpu-cuda-in-wsl
https://www.reddit.com/r/ROS/comments/1mxwhse/comment/na96uwd/
https://www.reddit.com/r/ROS/comments/1nttl0q/comment/ngx40c8/?context=3
You will also need an Xserver for Windows and set the $DISPLAY env var in your container.
Documentation contributions are welcome.

macOS

Running the container with x86 emulation should theoretically work, but we have never gotten this working.
You will need an Xserver for Mac.
You may find it easiest to create a VM, an x86 VM is recommended, but you are welcome to try on ARM.
Intel Macs should theoretically work with minimal issues.
Documentation contributions are welcome.

ARM

Some newer Windows 11 computers (and Apple and Linux) use the ARM instruction set. Unfortunately ARM is not officially supported by PX4 so you will either have to attempt to build the container yourself with some patches (see #Environment), run Docker with some sort of x86 emulation tool, or run Linux in an x86 VM.

Other Linux Distros

Thanks to containerized development any distro should be compatible with no issues. If you using a different distro please follow your distributions instructions for installing Docker, git, etc.

Do I actually need to use this?

If you are so inclined it is very much possible to get the required software running without the container. A good place to start would be the Dockerfile in the dev_env repo: https://github.com/UTAT-UAS/dev_env
Although if you are not doing it in some sort of Ubuntu 22.04 environment you will struggle.

Environment Installation🔗

Ubuntu Installation🔗

Skip if you have decided to use WSL2 or macOS.

IMPORTANT: Backup any important files on your main drive/partition, if you install Ubuntu correctly there will be no data loss but mistakes happen!

See the official docs for installing Ubuntu:

If you'd like a specific tutorial for installing dual booting Ubuntu, here are some options:

Dual boot (as in putting Linux and Windows on the same drive) can be avoided by using another drive, either by adding another to your desktop or using an external SSD on your laptop. The easiest way to install Linux to another SSD is to disconnect all other drives install as normal. Otherwise you will probably have to partition a boot sector manually (depending on the distro's installer).

If you'd like to try to keep Bitlocker and secure boot:

Docker🔗

You will need Docker, it can be installed here (click on Ubuntu): https://docs.docker.com/engine/install/

You will want to add yourself to the docker group: https://docs.docker.com/engine/install/linux-postinstall/

If you'd like to use Docker Desktop (easiest way to install on Windows and Mac):

For WSL2 see here: https://docs.docker.com/desktop/setup/install/windows-install/

For Mac see here: https://docs.docker.com/desktop/setup/install/mac-install/

For Linux see here: https://docs.docker.com/desktop/setup/install/linux/

Git🔗

At its core Git allows us to create "repositories" that tracks all files you tell it to. You "save" the repository by creating commits which contain the differences in text between the previous commit and your changes. This process of storing differences (or "diffs") allows the history of a codebase to be tracked and changes made readily apparent.

These tutorials will describe how to work with git from the command line. There are GUI (Graphical User Interface) programs to work with git as well, but they will not be covered here.

You can install Git here (click on your OS): https://git-scm.com/downloads

We will go over Git as we need it, but if you have no experience and would like to do some pre-reading these are some good places to start:

VS Code🔗

VS Code is a popular text editor developed by Microsoft, it is highly extendable with many plugins existing that can turn it into a fully featured integrated development environment (IDE).

Install VS Code if you haven't already: https://code.visualstudio.com/

You will also need the dev containers extension, just search for "dev containers" in the extension tab (Ctrl+Shift+X) or see here: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

If you'd like to learn more about dev containers see here for the full overview: https://code.visualstudio.com/docs/devcontainers/containers

GitHub🔗

GitHub is a remote Git repository host also owned by Microsoft, it allows us collaborate on a single Git repository.

SSH or Secure Shell Protocol is a key based authorization system used to connect to servers and services, and is the recommended way to interact with GitHub.

You will need to generate some keys: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

Add them to your GitHub account: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

These tutorials assume you will configure git and GitHub with SSH.

Environment🔗

Open a terminal in the folder/directory where you store your code.

Clone the repository with git clone git@github.com:UTAT-UAS/dev_env.git

https://github.com/UTAT-UAS/dev_env

Open the newly created dev_env folder with VS Code, you should be prompted by a pop-up in the bottom right to open this folder in a container, click Yes or equivalent.

If not open command palette ctrl+shift+p and search for Dev Containers: Open Folder in Container.

Dev Containers will now pull the prebuilt base image from ghcr.io and run some setup commands. This should take a few minutes with fast internet.

Eventually you should see Done. Press any key to close the terminal.

Building from source

The DockerFile is provided in .devcontainer/Dockerfile, do something like docker build dev_env:local .devcontainer to build the image locally. In order to use the image devcontainers is configured to use the docker-compose.yml to create and start the container, edit image for the uas service.
Note that this will take a long time (~15 to 30++ minutes).

Building on ARM

PX4 doesn't support this but if you'd like to try, edit the DockerFile to remove the problematic gcc/g++ libs in ~/PX4-Autopilot/Tools/setup/ubuntu.sh from the Installing NuttX dependencies section and install the multilib packages before running setup script. You will then need to build the container (see the README.md)
The packages that you might have to install are: 

gcc-multilib-arm-linux-gnueabi
gcc-multilib-arm-linux-gnueabihf
g++-multilib-arm-linux-gnueabi
g++-multilib-arm-linux-gnueabihf
Otherwise run with x86 emulation or use a VM.

Next🔗

Interacting with the Environment