Building 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. Download and install the desired toolchain to the user machine
  2. Clone the OpenThread Git repository
  3. From the repository's root directory:
    1. Run ./script/bootstrap to install the GNU toolchain and other dependencies (optional)
    2. Run ./bootstrap
    3. Configure and build, using one of two build modes:
      • Simple — 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. Run make -f examples/Makefile-<platform> <switches> to build the configuration
      • Advanced — core build with optional customization via configuration flags:
        1. Modify OpenThread compile-time constants in the /src/core/openthread-core-default-config.h file
        2. Run ./configure <flags> to generate a new Makefile
        3. Run make to build the configuration
  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:

TypeBuild ModeLocation
Compile-time constantsAnyListed in /src/core/openthread-core-default-config.h
Makefile build switchesSimpleListed in /examples/common-switches.mk
Configure option flagsAdvancedRun ./configure --help for a complete list

Build examples

Use a switch to enable functionality for an example platform in simple build mode. For example, to build the CC2538 example with Border Router support enabled:

make -f examples/Makefile-cc2538 BORDER_ROUTER=1

Use configure flags when running ./configure to generate an updated Makefile in advanced build mode. For example, to build OpenThread with Commissioner and Joiner support:

./configure --enable-commissioner --enable-joiner
make

Binaries

The following binaries are generated in /output/<platform>/bin from the build process, depending on the configure option flags used:

BinaryDescriptionConfigure option flag
ot-cli-ftd Full Thread device for SoC designs --enable-cli-app=(ftd|all)
ot-cli-mtd Minimal Thread device for SoC designs --enable-cli-app=(mtd|all)
ot-ncp-ftd Full Thread device for NCP designs --enable-ncp-app=(ftd|all)
ot-ncp-mtd Minimal Thread device for NCP designs --enable-ncp-app=(mtd|all)

If both flags are set to no, or not used, applications are not built, but OpenThread library files are still generated in /output/<platform>/lib for use in a project.

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.