GNU MCU Eclipse

A family of Eclipse CDT extensions and tools for GNU ARM & RISC-V development

How to install the ARM toolchain?

Overview

The build plug-in is highly configurable in terms of executable names and location, so you can use any 32/64-bits ARM GNU toolchain you prefer, but, for better results, the recommended toolchain for bare metal target applications is GCC ARM Embedded Toolchain (formerly GNU Tools for ARM Embedded Processors); for GNU/Linux target applications, the Linaro family of toolchains provides a large selection of choices, for various specific needs (little/big endian, 32/64-bits, etc).

Important notes: GDB 7.12, distributed with GCC 6.x, requires Neon.3 or higher, otherwise the suspend and terminate buttons in the debug perspective are not functional. arm-none-eabi-gdb 7.12 from the initial 6_2-2016q4-20161216 crashes on macOS; use 6-2017-q1-update or later.

Target vs host platform

Please note the distinction between the target platform and the host/development platform.

  • the target platform defines the environment where the application will be executed, and in general can be either a bare metal (the application sits directly on the hardware and has intimate control of it), and applications that sit on top of an operating system, usually a distribution of GNU/Linux optimised for embedded environments
  • the host/development platform is the platform where the development tools are executed, usually as cross compilers, and can be, in our case, any platform that supports Eclipse, for example Windows, macOS, GNU/Linux, etc.

Note: Be sure you select the proper toolchain for the target platform, otherwise builds will not succeed, or the generated applications will fail to run. Do not try to use the GCC ARM Embedded to build  GNU/Linux applications, because the executables will not run on anything than bare metal, and do not try to use the Linaro toolchains for bare metal applications.

The installation details described below assume the selection of the GCC ARM Embedded toolchain. For other toolchains, please follow the specific installation instructions.

Download

Due to portability reasons, the GNU MCU Eclipse plug-ins do not include any toolchain binaries, but they can be downloaded from the GNU ARM Embedded Toolchain.

Versions from 4_7 up to 6-2017-q1-update were tested and are known to work properly.

ARM Downloads

Windows

For Windows, the GNU ARM Embedded Toolchain is released in two versions:

  • a portable archive that can be installed in any location
  • a Windows setup that can install the binaries in the standard system location

Our prefered method is to install the binaries in the user home folder, but your mileage may vary.

Portable archive

To install the archive, the steps are:

  • download the latest gcc-arm-none-eabi-6-2017-q1-update-*-win*.zip file
  • open the archive in the file explorer
  • extract the GNU MCU Eclipse folder in %userprofile%\AppData\Local

According to Microsoft, this is the recommended location for installing user specific packages, and the GNU MCU Eclipse plug-ins can automatically identify the toolchain if installed in this location.

In addition, the GNU MCU Eclipse plug-ins also check the following locations (POSIX paths):

${user.home}/AppData/Local/GNU Tools ARM Embedded;\
${user.home}/opt/GNU Tools ARM Embedded;\
${user.home}/opt/gnu-tools-arm-embedded;\
${user.home}/local/GNU Tools ARM Embedded;\
${user.home}/local/gnu-tools-arm-embedded;\
C:/opt/GNU Tools ARM Embedded;\
C:/opt/gnu-tools-arm-embedded;\
C:/Program Files/GNU Tools ARM Embedded;\
C:/Program Files (x86)/GNU Tools ARM Embedded;\
D:/Program Files/GNU Tools ARM Embedded;\
D:/Program Files (x86)/GNU Tools ARM Embedded

It is recommended to use one of these locations, since the plug-ins will automatically set the default toolchain path to the most recently installed toolchain found in these folders.

Setup

If you decide to install the toolchain in a system location, you can use the common setup procedure:

  • download the latest Windows installer .exe file (currently gcc-arm-none-eabi-6-2017-q1-update-win32.exe, about 84 MB)
  • locate the file (usually in the ...\Downloads\  folder) and double click it to start the installer
  • authenticate with the administrative password, to allow the installer write in system locations

    MS_admin

  • select the desired language
  • confirm that you want to install the toolchain
  • accept the terms of the license agreement
  • accept the destination folder, usually a version specific sub-folder of C:\Program Files\

    Note: It is highly recommended to do not change the install path

    The destination folder

  • wait a few moments for the installer to copy files
  • in the final window be sure you disable adding the toolchain path to the environment

    Disable adding toolchain path to environment

  • read the readme.txt file
  • test if the compiler is functional; use the actual install path:

    C:\>"C:\Program Files\GNU Tools ARM Embedded\4.8 2014q2\bin\arm-none-eabi-gcc.exe" --version
    arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.8.4 20140526 (release) [ARM/embedded-4_8-branch revision 211358]
    

The complete toolchain documentation is available in the ...\share\doc\pdf\ folder.

If you’ll ever need to remove the toolchain, there is an uninstall.exe program available in the toolchain root folder.

For Windows, the next step would be to install the build tools (make & rm).

macOS

For macOS, the GNU ARM Embedded Toolchain is released as a portable archive, that can be installed in any location.

  • download the latest macOS install tarball file (currently gcc-arm-none-eabi-6-2017-q1-update-mac.tar.bz2, about 99 MB)
  • locate the file (usually in the ${HOME}/Downloads folder)
  • decide on a location to install the toolchain; the recommended folder is ${HOME}/opt/

    Note: It is highly recommended to use this path, since the GNU MCU Eclipse plug-ins can automatically identify the toolchain if installed in this location.

    In addition, the GNU MCU Eclipse plug-ins also check the following locations:

    ${user.home}/opt:\
    ${user.home}/local:\
    /usr/local:\
    /opt
    
  • unpack the archive in the destination folder
  • the result should be a folder like ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update

    $ mkdir -p ${HOME}/opt
    $ cd ${HOME}/opt
    $ tar xjf ~/Downloads/gcc-arm-none-eabi-6-2017-q1-update-mac.tar.bz2
    $ chmod -R -w ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update
    
  • test if the compiler is functional; use the actual install path:

    $ ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-gcc --version
    arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors 6-2017-q1-update) 6.3.1 20170215 (release) [ARM/embedded-6-branch revision 245512]
    

    DO NOT add the toolchain path to the user or system path!

The complete toolchain documentation is available in the .../share/doc/pdf/ folder.

If you’ll ever need to remove the toolchain, only remove the ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update, there are no other components stored in any system folders.

MacPorts

In case you have MacPorts installed, be sure you remove the MacPorts path from the user path (edit the .profile in your home folder and comment out the line where /opt/local/ is added in front of the PATH), especially if you installed any toolchain inside MacPorts, since this will be a serious source of confusion.

GNU/Linux

For GNU/Linux, the GNU ARM Embedded Toolchain is released as a portable archive, that can be installed in any location.

The following steps were performed on Ubuntu 14.04 LTSx64 (please adjust them accordingly for other distributions):

  • starting with version 6.x, GNU/Linux toolchains are 64-bits applications, and should work directly on most modern distributions;

  • in older versions, the toolchain executables are 32-bits apps; when running on 64-bits machines, be sure you install the following 32-bits libraries (for different versions check the toolchain README for the actual list):

    $ sudo apt-get -y install lib32z1 lib32ncurses5 lib32bz2-1.0
    
  • on Ubuntu 15.04 the following libraries are required:

    $ sudo apt-get -y install lib32ncurses5
    
  • on Ubuntu 12 LTSx64 all 32-bits libraries were packed in ia32-libs, so you can also use, but be prepared to get a lot of useless libraries:

    $ sudo apt-get -y install ia32-libs
    
  • download the latest Linux install tarball file from ARMDeveloper (currently gcc-arm-none-eabi-6-2017-q1-update-linux.tar.bz2, more than 95 MB)

    Note: DO NOT install the ARM GCC package that comes with your distribution, especially if it is newer than the one provided by Launchpad, since generally it is not supported, and debugging sessions might fail.

  • locate the file (usually in the ${HOME}/Downloads/  folder)
  • decide on a location to install the toolchain; the recommended folder is ${HOME}/opt/
  • unpack the archive in the destination folder

    Note: It is highly recommended to do not change the install path, since the plug-in tries to automatically discover the toolchain by searching only a limited set of possible locations (${HOME}/local, ${HOME}/opt, /usr/local).

    $ mkdir -p ${HOME}/opt
    $ cd ${HOME}/opt
    $ tar xjf ~/Downloads/gcc-arm-none-eabi-6-2017-q1-update-linux.tar.bz2
    $ chmod -R -w ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update
    
  • the result should be a folder like ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update
  • test if the compiler is functional; use the actual install path:

    $ ${HOME}/opt/gcc-arm-none-eabi-4_8-2014q1/bin/arm-none-eabi-gcc --version
    arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.8.3 20140228 (release) [ARM/embedded-4_8-branch revision 208322]
    

    DO NOT add the toolchain path to the user or system path!

The complete toolchain documentation is available in the .../share/doc/pdf/ folder.

If you’ll ever need to remove the toolchain, only remove the ${HOME}/opt/gcc-arm-none-6-2017-q1-update, there are no other components stored in any system folders.

Toolchain path

To be sure you did not miss this recommendation, here it is again:

DO NOT add the toolchain path to the user or system path!

If there would be only one single version of one single toolchain in existence, then it wouldn’t be a problem, but as soon as you start real world applications, you will face at least the need to keep multiple versions of the same toolchain installed, if not multiple toolchains, and this is when your trouble starts.

The GNU MCU Eclipse plug-in has an advanced toolchain path management (presented in more detail in the separate page). Use it!

GDB 7.12

GDB 7.12 distributed with the initial GCC 6.2 (gcc-arm-none-eabi-6_2-2016q4-20161216) has several issues (crashes on macOS and is incompatible with Neon.2).

The recommendation is to use the update version gcc-arm-none-eabi-6-2017-q1-update, or later.