Toolchain Setup Guide

This page explains how to set up ARM GCC 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!
4. If you don't already have it, install Python 3 so that you can run python from the command line. Don't forget to click the "add to path" checkbox when installing Python!
5. 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.16.
   • For most recent distros, e.g. Ubuntu 20.04 and newer, you can just use the package manager CMake package.
   • For Ubuntu 16.04 and 18.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. Lastly, make sure Pip is installed to your system python. This depends on your specific distro, but on Ubuntu you should be able to run sudo apt-get install python3-pip python3-setuptools python3-wheel.

The toolchain should now be set up!

Other Useful Tools

Besides the ARM toolchain, there are some other tools that you might want/need as you work on Mbed OS development. Mainly these will provide debugging and flashing support for different boards and chips.