Configure Build Environment for Torizon Containers
Introduction
In this article, you will learn the basic setup of a development environment for Torizon, regardless of your choice of code editor/IDE or revision control system. As applications are integrated into Torizon OS using containers, this setup mainly involves configuring a Docker environment. Here you will find instructions for both Linux and Windows development environments.
Torizon Development Environment
While it is possible to build and configure containers directly on the target for quick tests or prototypes, this approach is generally not suitable for projects that require long-term maintenance.
The recommended workflow for Torizon involves the cross-compilation of containers. In this case, you should define the necessary configuration steps to initialize your container in a Dockerfile and use it to build the container on your host machine:
- Installing packages.
- Changing configuration file.
- Adding application-specific content.
Your development machine will likely use an x86/x64 processor, while Toradex's modules have Arm SOCs. To build containers that can run on a different processor architecture, you have to properly configure the Docker environment according to the instructions presented in this article.
This article complies with the Typographic Conventions for Toradex Documentation.
Prerequisites
- Host machine with Windows or Linux OS.
Windows
Follow these steps to configure your development environment on Windows.
Install WSL 2
The Windows Subsystem for Linux (WSL) enables the use of most Linux command-line tools, utilities and applications directly on Windows. It also lets you leverage the IDE Extension with Visual Studio Code installed on your Windows machine. If you are unfamiliar with WSL and want to learn more, see Introduction to Windows Subsystem for Linux (WSL).
Choose one of the Torizon IDE officially supported Linux distributions.
Check which version of WSL you are running. If WSL 1 is installed, upgrade version from WSL 1 to WSL 2.
You will find more information in the following articles:
Install Docker Engine
There are two options for managing Docker containers: Docker Engine and Docker Desktop.
- Docker Engine is an open-source technology that provides the Docker daemon and CLI commands for containerizing applications.
- Docker Desktop provides, besides Docker Engine, a GUI and a set of proprietary tools.
Since Docker Desktop is licensed under the Docker Subscription Service Agreement, we recommend using Docker Engine, which is licensed under the Apache License, Version 2.0.
Open a WSL terminal: You can run the
wsl
command in a PowerShell terminal.Install Docker Engine in WSL: To ensure the correct installation of Docker Engine, follow the instructions for the specific Linux distribution you have installed with WSL.
Linux
Follow these steps to configure your development environment on Linux.
Install Docker Engine
There are two options for managing Docker containers: Docker Engine and Docker Desktop.
- Docker Engine is an open-source technology that provides the Docker daemon and CLI commands for containerizing applications.
- Docker Desktop provides, besides Docker Engine, a GUI and a set of proprietary tools.
Since Docker Desktop is licensed under the Docker Subscription Service Agreement, we recommend using Docker Engine, which is licensed under the Apache License, Version 2.0.
Install Docker Engine: The release of Docker provided by some distribution feeds is not up-to-date. To ensure the correct Docker installation, follow the instructions for your distribution in the Docker documentation.
Enable Arm emulation
Arm emulation makes it possible to run Arm instructions on Intel x86-64 architectures. That is, you can run binaries compiled for the Arm instruction set on an x86 computer.
To enable this emulation to be used with Docker, run the following command:
Use the same command for Windows (Docker Desktop Hyper-V VM or Docker Desktop using WSL 2 as backend) and Linux distributions.
$ docker run --rm -it --privileged torizon/binfmt
This operation will run a privileged container, it will run for the time required to enable Arm emulation using binfmt. It should be a safe operation.
Enabling Arm emulation through this method is NOT persistent. After reboots, you have to run this command again to re-enable Arm emulation.
This command will install and register the interpreters that will know how to run the arm32v7
and arm64v8
instructions on your Intel x86 development PC. This use the Kernel Linux support for miscellaneous binary formats feature.
To test whether the interpreters have been successfully installed, run the commands:
Test arm32v7
$ docker run --rm -it --pull always --platform linux/arm/v7 debian arch
The return must be:
armv7l
Test arm64v8
$ docker run --rm -it --pull always --platform linux/arm64/v8 debian arch
The return must be:
aarch64
Common Issues
Arm Emulation
Arm emulation is not persistent and must be enabled at every boot. Therefore, it is common to encounter exec format error
when building or running an Arm container on an x86 platform:
$ docker run --rm -it --platform linux/arm64/v8 debian arch
WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64/v4) and no specific platform was requested
exec /usr/bin/arch: exec format error
To fix this issue, follow the steps on the Enable Arm emulation section.