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 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. Build the configuration:

           make -f examples/Makefile-<platform> <switches>

      • 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. Generate a new Makefile:

           ./configure <flags>

        3. Build the configuration:

           make

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:

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:

If these flags 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.