Skip to content

Toolchain Setup Guide

Jump to bottom Edit New page
Jamie Smith edited this page Oct 5, 2023 · 28 revisions

This page explains how to set up ARM GCC and other tools on your computer so that you can compile Mbed CE projects.

On Windows:

  1. Get CMake by downloading the installer from here. If you already have CMake installed, make sure it's at least version 3.16. Make sure to select "Add CMake to the system PATH for all users" in the installer!
  2. Download the latest Ninja Build binary from here (grab ninja-win.zip). Then, you need to extract the exe file to somewhere on your PATH. Note: It might be convenient to put it into the CMake bin folder (C:\Program Files\CMake\bin) since the CMake installer has already added that to your PATH.
  3. Go to ARM's toolchain download page and download the exe installer under "Windows (mingw-w64-i686) hosted cross toolchains" > "AArch32 bare-metal target (arm-none-eabi)". Then, execute it and go through the installer, making sure to check the "Add path to environment variable" box!

ARM toolchain installer

  1. If you don't already have it, install Python 3 so that you can run python from the command line. Note: Windows Store version not recommended. To make sure Python gets installed correctly, follow the install process below:

On the first screen, select the "Add Python 3.x to PATH" checkbox, then click "Customize installation" Python installer screen 1

Click Next on the second screen.

Python installer screen 2

On the third screen, check "Install for all users". Also, make sure "Add Python to environment variables" is checked.

Python installer screen 3

The installer should now run and complete.

  1. Reboot your machine so that the changes to your PATH are applied.

The toolchain should now be set up!

On Mac:

  1. If you don't already have Homebrew, install it according to its instructions here.
  2. Install cmake and ninja with brew install cmake ninja in the terminal.
  3. Add a Brew remote for the ARM toolchain: brew tap osx-cross/arm
  4. Install the toolchain: brew install arm-gcc-bin
  5. Lastly, make sure Pip is installed to your system python. In a terminal, run sudo -H python3 -m easy_install pip

The toolchain should now be set up!

On Linux:

note: We do not recommend using the official Debian/Ubuntu gcc-arm-none-eabi package due to an as-yet-unfixed bug that prevents proper compilation of Mbed OS. As far as we can tell, the packages from ARM do not have this bug.

  1. Install CMake >= 3.19.
    • For recent distros, e.g. Ubuntu 22.04 and newer, you can just use the package manager CMake package.
    • For Ubuntu 16.04, 18.04, and 20.04, use this APT repo.
    • Many distros can also utilize the CMake snap package.
    • Otherwise, if your distro doesn't have a version recent enough, you may have to build it from source.
  2. Install Ninja Build. On Ubuntu you can install it with sudo apt-get install ninja-build, though other distros may vary.
  3. Install some dependency packages for the arm toolchain: sudo apt-get install libncurses5 libncursesw5
  4. Go to ARM's toolchain download page and download the tar.xz toolchain under "x86_64 Linux hosted cross toolchains" > "AArch32 bare-metal target (arm-none-eabi)".
    • Note: If using an ARM64 machine like a Raspberry Pi, get the "AArch64 Linux hosted" build instead.
  5. Open a terminal in the folder where you downloaded the tar.xz file, and extract it with tar xf arm-gnuXXXX.tar.xz (replace "arm-gnuXXXX" with the full name of the toolchain file)
  6. Using the terminal, copy the entire folder to /usr/local on your machine by running: sudo mv arm-gnuXXXX /usr/local/gcc-arm.
  7. Navigate to your home directory by typing cd ~. Then, create a bash profile if you don't already have one by typing nano .bash_profile
    • If you use zsh, use .zshrc instead of .bash_profile in these steps
  8. Add the following line to the end of your .bash_profile file: export PATH=/usr/local/gcc-arm/bin:$PATH
  9. Save the file and exit by hitting Ctrl-O, then Enter, then Ctrl-X
  10. Restart all terminal windows or run source ~/.bash_profile in all open terminal windows.
  11. Install some Python dependency packages into your system Python: sudo apt-get install python3-intelhex python3-prettytable python3-future python3-jinja2 python3-click python3-git python3-tqdm python3-tabulate python3-requests python3-psutil python3-pyudev python3-typing-extensions python3-serial python3-dotenv
    • Note: If you have an alternate python interpreter installed (e.g. Anaconda, or a newer Python installed from a PPA), you might need to install these packages into this interpreter in the appropriate way.

The toolchain should now be set up!

Extras: Installing Debuggers

If you want to debug your code, you will also need to install one of the upload methods that supports debugging. Which one to use depends on your specific setup -- generally openocd and pyocd can be used on all processors, but others such as STM32Cube only work with specific ones. See the Upload Methods page for details about the methods and how to install them.

Optional: Install CCache

CCache will speed up compilation a lot. The current download can be found here: https://ccache.dev/ Windows: Unzip the downloaded files to a program directory. Add the path to the environment path variable (Win Key, type 'env' for quick access). Then CMake will find the CCache tool and add it to CMakeCache.txt.

Add a custom footer
Add a custom sidebar
Clone this wiki locally