This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

3rd Party Toolchains

A “3rd party toolchain” is an officially supported toolchain provided by an external organization. Several of these are available.

GNU Arm Embedded

Warning

Do not install the toolchain into a path with spaces.

  1. Download and install a GNU Arm Embedded build for your operating system and extract it on your file system.

    Note

    On Windows, we’ll assume you install into the directory C:\gnu_arm_embedded.

    Warning

    On macOS Catalina or later you might need to change a security policy for the toolchain to be able to run from the terminal.

  2. Set these environment variables:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to gnuarmemb.

    • Set GNUARMEMB_TOOLCHAIN_PATH to the toolchain installation directory.

  3. To check that you have set these variables correctly in your current environment, follow these example shell sessions (the GNUARMEMB_TOOLCHAIN_PATH values may be different on your system):

    # Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
gnuarmemb
$ echo $GNUARMEMB_TOOLCHAIN_PATH
/home/you/Downloads/gnu_arm_embedded

# Windows:
> echo %ZEPHYR_TOOLCHAIN_VARIANT%
gnuarmemb
> echo %GNUARMEMB_TOOLCHAIN_PATH%
C:\gnu_arm_embedded

    Warning

    On macOS, if you are having trouble with the suggested procedure, there is an unofficial package on brew that might help you. Run brew install gcc-arm-embedded and configure the variables

    • Set ZEPHYR_TOOLCHAIN_VARIANT to gnuarmemb.

    • Set GNUARMEMB_TOOLCHAIN_PATH to the brew installation directory (something like /usr/local)

Arm Compiler 6

  1. Download and install a development suite containing the Arm Compiler 6 for your operating system.

  2. Set these environment variables:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to armclang.

    • Set ARMCLANG_TOOLCHAIN_PATH to the toolchain installation directory.

  3. The Arm Compiler 6 needs the ARMLMD_LICENSE_FILE environment variable to point to your license file or server.

For example:

# Linux, macOS, license file:
export ARMLMD_LICENSE_FILE=/<path>/license_armds.dat
# Linux, macOS, license server:
export ARMLMD_LICENSE_FILE=8224@myserver

# Windows, license file:
> set ARMLMD_LICENSE_FILE=c:\<path>\license_armds.dat
# Windows, license server:
> set ARMLMD_LICENSE_FILE=8224@myserver

  1. If the Arm Compiler 6 was installed as part of an Arm Development Studio, then you must set the ARM_PRODUCT_DEF to point to the product definition file: See also: Product and toolkit configuration. For example if the Arm Development Studio is installed in: /opt/armds-2020-1 with a Gold license, then set ARM_PRODUCT_DEF to point to /opt/armds-2020-1/gold.elmap.

    Note

    The Arm Compiler 6 uses armlink for linking. This is incompatible with Zephyr’s linker script template, which works with GNU ld. Zephyr’s Arm Compiler 6 support Zephyr’s CMake linker script generator, which supports generating scatter files. Basic scatter file support is in place, but there are still areas covered in ld templates which are not fully supported by the CMake linker script generator.

    Some Zephyr subsystems or modules may also contain C or assembly code that relies on GNU intrinsics and have not yet been updated to work fully with armclang.

Intel oneAPI Toolkit

  1. Download Intel oneAPI Base Toolkit

  2. Assuming the toolkit is installed in /opt/intel/oneApi, set environment using:

    # Linux, macOS:
export ONEAPI_TOOLCHAIN_PATH=/opt/intel/oneapi
source $ONEAPI_TOOLCHAIN_PATH/compiler/latest/env/vars.sh

# Windows:
> set ONEAPI_TOOLCHAIN_PATH=C:\Users\Intel\oneapi

    To setup the complete oneApi environment, use:

    source  /opt/intel/oneapi/setvars.sh

    The above will also change the python environment to the one used by the toolchain and might conflict with what Zephyr uses.

  3. Set ZEPHYR_TOOLCHAIN_VARIANT to oneApi.

DesignWare ARC MetaWare Development Toolkit (MWDT)

  1. You need to have ARC MWDT installed on your host.

  2. Set these environment variables:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to arcmwdt.

    • Set ARCMWDT_TOOLCHAIN_PATH to the toolchain installation directory. MWDT installation provides METAWARE_ROOT so simply set ARCMWDT_TOOLCHAIN_PATH to $METAWARE_ROOT/../ (Linux) or %METAWARE_ROOT%\..\ (Windows)

  3. To check that you have set these variables correctly in your current environment, follow these example shell sessions (the ARCMWDT_TOOLCHAIN_PATH values may be different on your system):

    # Linux:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
arcmwdt
$ echo $ARCMWDT_TOOLCHAIN_PATH
/home/you/ARC/MWDT_2019.12/

# Windows:
> echo %ZEPHYR_TOOLCHAIN_VARIANT%
arcmwdt
> echo %ARCMWDT_TOOLCHAIN_PATH%
C:\ARC\MWDT_2019.12\

Crosstool-NG

You can build toolchains from source code using crosstool-NG.

  1. Follow the steps on the crosstool-NG website to prepare your host.

  2. Follow the Zephyr SDK with Crosstool NG instructions to build your toolchain. Repeat as necessary to build toolchains for multiple target architectures.

    You will need to clone the sdk-ng repo and run the following command:

    ./go.sh <arch>

    Note

    Currently, only i586 and Arm toolchain builds are verified.

  3. Set these environment variables:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to xtools.

    • Set XTOOLS_TOOLCHAIN_PATH to the toolchain build directory.

  4. To check that you have set these variables correctly in your current environment, follow these example shell sessions (the XTOOLS_TOOLCHAIN_PATH values may be different on your system):

    # Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
xtools
$ echo $XTOOLS_TOOLCHAIN_PATH
/Volumes/CrossToolNGNew/build/output/

Cadence Tensilica Xtensa C/C++ Compiler (XCC)

  1. Obtain Tensilica Software Development Toolkit targeting the specific SoC on hand. This usually contains two parts:

    • The Xtensa Xplorer which contains the necessary executables and libraries.

    • A SoC-specific add-on to be installed on top of Xtensa Xplorer.

      • This add-on allows the compiler to generate code for the SoC on hand.

  2. Install Xtensa Xplorer and then the SoC add-on.

    • Follow the instruction from Cadence on how to install the SDK.

    • Depending on the SDK, there are two set of compilers:

      • GCC-based compiler: xt-xcc and its friends.

      • Clang-based compiler: xt-clang and its friends.

  3. Make sure you have obtained a license to use the SDK, or has access to a remote licensing server.

  4. Set these environment variables:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to xcc or xcc-clang.

    • Set XTENSA_TOOLCHAIN_PATH to the toolchain installation directory.

    • Set XTENSA_CORE to the SoC ID where application is being targeting.

    • Set TOOLCHAIN_VER to the Xtensa SDK version.

  5. For example, assuming the SDK is installed in /opt/xtensa, and using the SDK for application development on intel_s1000_crb, setup the environment using:

    # Linux
export ZEPHYR_TOOLCHAIN_VARIANT=xcc
export XTENSA_TOOLCHAIN_PATH=/opt/xtensa/XtDevTools/install/tools/
export XTENSA_CORE=X6H3SUE_RI_2018_0
export TOOLCHAIN_VER=RI-2018.0-linux

  6. To use Clang-based compiler:

    • Set ZEPHYR_TOOLCHAIN_VARIANT to xcc-clang.

    • Note that the Clang-based compiler may contain an old LLVM bug which results in the following error:

      /tmp/file.s: Assembler messages:
/tmp/file.s:20: Error: file number 1 already allocated
clang-3.9: error: Xtensa-as command failed with exit code 1

      If this happens, set XCC_NO_G_FLAG to 1.

      • For example:

        # Linux
export XCC_NO_G_FLAG=1

    • Also note that setting XCC_USE_CLANG to 1 and ZEPHYR_TOOLCHAIN_VARIANT to xcc is deprecated. Set ZEPHYR_TOOLCHAIN_VARIANT to xcc-clang instead.