This article demonstrates how to set up and use the GNU ARM embedded toolchain on a GNU/Linux system.

Only GNU/Linux-based OS are supported, but the same principles may be applicable to Mac as well.

Be careful

Please follow the instructions exactly, unless you're an experienced user and really know what you're doing!


Avoid package repositories

Even if your OS provides some versions of the toolchain from its package repositories (like Ubuntu-based distributions do), you should not use them, because historically they were rather troublesome and unreliable. If you already have these installed on your PC, please make sure to remove them before continuing, otherwise things will not work. For example, the following command can be used on any Ubuntu-based OS to ensure that no unwanted toolchain has crept in by accident: sudo apt-get purge *arm-none-eabi*.

Download the required version of the toolchain from any of the below listed websites (if you are not sure what version you need, pick the latest available):

Extract the downloaded archive into ~/opt/gcc-arm-none-eabi-7/, where 7 is the major version number of the downloaded toolchain that may be different in your case. If the opt directory doesn't exist, create it. The resulting directory layout should look similar to this:

$ tree -L 2 ~/opt/gcc-arm-none-eabi-7
├── arm-none-eabi
│   ├── bin
│   ├── include
│   ├── lib
│   └── share
├── bin
│   ├── arm-none-eabi-addr2line
│   ├── arm-none-eabi-ar
│   ├── <...skipped...>
│   └── arm-none-eabi-strip
├── lib
│   ├── gcc
│   ├── ->
│   ├── ->
│   └──
└── share
    ├── doc
    └── gcc-arm-none-eabi

You may want to download additional versions of the toolchain and extract them into different directories following the same naming pattern.

Configuring the environment variables

Open your shell profile file ~/.profile (you may need a different file if you're using an unpopular configuration or a custom shell, but in that case you will know what to do). Add the following near the end of it:

export PATH=$PATH:~/opt/gcc-arm-none-eabi/bin/

Then close the current command line session and start a new one in order for the changes to take effect (the profile file is read upon initialization of a shell session).

The added code ensures that the toolchain is in the PATH directory of the current user. It is therefore required that if you're using an IDE, it should have access to the PATH variables of your user environment, otherwise it won't be able to find the toolchain.

Switching between different versions

An attentive reader might have noticed that the guide has instructed them to extract the toolchain into ~/opt/gcc-arm-none-eabi-7/, whereas the configured PATH extension points to a different directory tree ~/opt/gcc-arm-none-eabi/bin/. This is no accident!

The final step that is needed to make everything work is to rename the directory of the toolchain of the required version into ~/opt/gcc-arm-none-eabi/, thus making the above PATH reference valid. Shall you need to switch to a different version of the toolchain, you should just rename the directory ~/opt/gcc-arm-none-eabi/ into ~/opt/gcc-arm-none-eabi-7/ again (the name may be different dependent on the version of the toolchain), and repeat the trick for the new toolchain.

You can verify which version is currently active by running the command arm-none-eabi-g++ --version.

Avoid common pitfalls

Forget about sudo

Do not attempt to invoke any part of the toolchain as a superuser. It doesn't make sense, it won't work, and it may bring your build directory into an invalid state.

Make sure your USB devices are configured properly

If you're using a USB debugger such as the Zubax Dronecode Probe, please ensure that the access permissions are configured correctly.