Build OpenThread

Toolchains

The primary supported toolchain for building OpenThread is GNU Autotools.

GNU Autotools

Instructions on building examples with GNU Autotools can be found in each example's platform folder. Note that the intent of these examples is to show the minimal code necessary to run OpenThread on each respective platform. As such, they do not highlight the platform's full capabilities.

Further configuration during builds might be necessary, depending on your use case.

GNU Autotools — Nest Labs build

Nest Labs has created a customized, turnkey build system framework, based on GNU Autotools. This is used for standalone software packages that need to support:

  • building on and targeting against standalone build host systems
  • embedded target systems using GCC-based or -compatible toolchains

The Nest Labs build of GNU Autotools is recommend for use with OpenThread because some build host systems might not have GNU Autotools, or might have different versions and distributions. This leads to inconsistent primary and secondary Autotools output, which results in a divergent user and support experience. The Nest Labs build avoids this by providing a pre-built, qualified set of GNU Autotools with associated scripts that do not rely on the versions of Autotools on the build host system.

This project is typically subtreed (or git submoduled) into a target project repository and serves as the seed for that project's build system.

To learn more, or to use this tool for your OpenThread builds, see the README.

How to build OpenThread

The steps to build OpenThread vary depending on toolchain, user machine, and target platform.

The most common workflow is:

  1. Set up the build environment and install the desired toolchain:
    1. To build directly on a machine, see the Simulation Codelab for detailed instructions
    2. To use a Docker container with a pre-configured environment, download and run the OpenThread environment image:
      docker pull openthread/environment:latest
      docker run -it --rm openthread/environment bash
  2. Within your chosen environment, clone the OpenThread Git repository:
    git clone https://github.com/openthread/openthread
  3. From the cloned repository's root directory:
    1. Install the GNU toolchain and other dependencies (optional):
      ./script/bootstrap
    2. Set up the environment:
      ./bootstrap
    3. Configure and build, using pre-defined platform examples with optional customization via common switches:
      1. Modify OpenThread compile-time constants in the selected platform's /examples/platforms/<platform>/openthread-core-<platform>-config.h file
      2. Build the configuration:
        make -f examples/Makefile-<platform> <switches>
  4. Flash the desired binary to the target platform. All generated binaries are located in /output/<platform>/bin. When using Advanced Mode, the <platform> may be specific to the user's machine. For example, x86_64-apple-darwin.

Specific instructions on building supported platforms with GNU Autotools can be found in each example's platform folder.

Configuration

You can configure OpenThread for different functionality and behavior during the build process. Available configuration options are detailed at the following locations:

TypeLocation
Compile-time constantsListed in all the header files in /src/core/config
Makefile build switchesListed in /examples/common-switches.mk

Build examples

Use a switch to enable functionality for an example platform. For example, to build the CC2538 example with Commissioner and Joiner support enabled:

make -f examples/Makefile-cc2538 COMMISSIONER=1 JOINER=1

Or, to build the nRF52840 example with the Jam Detection feature enabled:

make -f examples/Makefile-nrf52840 JAM_DETECTION=1

Binaries

The following binaries are generated in /output/<platform>/bin from the build process. To determine which binaries are generated, use configure option flags with the ./configure command to generate an updated Makefile for building. For example, to build OpenThread and generate only the CLI binaries:

./configure --enable-cli
make
BinaryDescriptionConfigure option flags
ot-cli-ftd Full Thread device for SoC designs --enable-cli
--enable-ftd
ot-cli-mtd Minimal Thread device for SoC designs --enable-cli
--enable-mtd
ot-ncp-ftd Full Thread device for NCP designs --enable-ncp
--enable-ftd
ot-ncp-mtd Minimal Thread device for NCP designs --enable-ncp
--enable-mtd
ot-rcp Host / 802.15.4 Controller design --enable-ncp
--enable-radio-only

If neither these flags nor a platform example are not used, applications are not built but OpenThread library files are still generated in /output/<platform>/lib for use in a project.

Check the example Makefiles for each platform to see which flags each platform supports. For example, the TI CC2650 does not support FTDs. For more information on FTDs and MTDs, see the Thread Primer. For more information on SoC and NCP designs, see Platforms.

The process to flash these binaries varies across example platforms. See the READMEs in each platform's example folder for detailed instructions.

Build Support Packages

Build Support Packages (BSPs) are found in /third_party. BSPs are additional third-party code used by OpenThread on each respective platform, generally included when porting OpenThread to a new hardware platform.