Start.
Please note.
Though we highly recommend the following development environment set-up to work with the embedul.ar framework, it is not mandatory. We invite you to adapt the instructions to your preference and contribute your recipe.
Automatic installation scripts will be available at a later stage.
What you’ll need.
A Linux distribution.
Debian 11 or Ubuntu 22.04 LTS.
Package manager instructions (apt install) are for the APT package manager.
You can easily adapt those to your preferred Linux distribution own package manager.
System tools.
- Git source-control management.
- GNU Make, to invoke the embedul.ar build system.
- Build EAR, to intercept make commands and build a “compile_commands.json” compilation database.
- A native GCC compiler, to build programs targeted to your PC architecture.
- OpenOCD, to connect your PC to debug interfaces on embedded systems.
sudo apt install git make bear gcc openocd
embedul.ar framework.
1) Download the framework source from the GitHub repository by using Git. On a terminal, go to where you want the source code root directory to reside, for example, “cd ~”, and execute the following command:
cd ~
git clone https://github.com/embedular/embedul.ar.git
The framework has many example projects you can try out. We also highly recommend cloning an existing stand-alone application to use as a template for your projects, for example, a Wolfenstein 3D port. You can place an application anywhere on your local filesystem, except inside the embedul.ar framework directory itself, for example, this is invalid: “embedul.ar/wolf3d.ar”.
cd ~
git clone https://github.com/embedular/wolf3d.ar.git
2) Export the environment variable LIB_EMBEDULAR_PATH containing the path from where you cloned the embedul.ar framework. We recommend simply copying the provided .bash_profile file to your home directory or appending its contents to your file if it already exists. Review the comments on your copy, and edit accordingly.
SDL library.
The Simple DirectMedia Layer brings a common video, audio and input API to diverse desktop, mobile or even web-based operating systems. The embedul.ar framework uses SDL to simulate generic embedded systems hardware on a cross-platform, os-hosted, native build target.
1) Install the development libraries of SDL2 and SDL2_Mixer:
sudo apt install libsdl2-dev libsdl2-mixer-dev
VSCodium.
Open source binary distribution of Visual Studio Code.
Plus extensions to debug embedded systems.
1) Follow the installation instructions for Debian/Ubuntu (deb package).
2) Start VSCodium. Press Ctrl+Shift+X and install the following extensions: “clangd”, “Hex Editor”, and “Native Debug”.
3) To work with Arm® Cortex®-based boards, install the extensions: “Arm Assembly”, and “Cortex-Debug”.
Arm® Embedded GNU Toolchain.
To cross-compile to Arm® Cortex® processors running bare-metal:
1) Download xpack-arm-none-eabi-gcc-13.3.1-1.1-linux-x64.tar.gz from the xPack project page.
2) On a terminal, step where you downloaded the file, for example, “cd ~/Downloads”. Then use the following console commands to decompress the toolchain to /opt:
cd ~/Downloads
sudo tar -xvf xpack-arm-none-eabi-gcc-13.3.1-1.1-linux-x64.tar.gz -C /opt
3) Add the toolchain binary path “/opt/xpack-arm-none-eabi-gcc-13.3.1-1.1/bin” to the system’s PATH environment variable. To achieve that, we recommend to copy the provided arm-gnu-toolchain.sh file to your “/etc/profile.d” directory.
4) Log out and log in to your system, then check if the toolchain binary path is actually in the system’s PATH environment variable:
echo $PATH | grep arm-none-eabi
/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/snap/bin:/opt/xpack-arm-none-eabi-gcc-13.3.1-1.1/bin
If the command displays nothing, go back to check step three. If the problem persists, visit the Support Q&A.
5) Check if the command “arm-none-eabi-gcc –version” works. It should read:
arm-none-eabi-gcc --version
arm-none-eabi-gcc (xPack GNU Arm Embedded GCC x86_64) 13.3.1 20240614
Copyright (C) 2023 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
(optional) To rebuild documentation.
The embedul.ar framework uses Sphinx and the Hawkmoth extension to mix reStructuredText files with “C” source code annotations.
1) Since Hawkmoth requires a Sphinx version that, at the time of this writing, is still not available in Debian 11, you must install it by using PIP:
sudo apt install python3-pip
pip3 install sphinx hawkmoth sphinx_rtd_theme
2) PIP will install Python scripts in “/home/{username}/.local/bin.” You should include the path in the system’s PATH environment variable. The file “embedul.ar/install/home/username/.bash_profile” already does that. The same instructions apply in this case.
What’s next
Let’s test the development environment by building your first “hello world” application.
Then, we can take a brief VSCodium tutorial for embedded systems.
Tux classic flat look author: Larry Ewing, Sergey Smith (FoxyRiot). VSCodium logo author: Christophe Larsonneur (MIT License).
Arm and Cortex are registered trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere.