OpenWrt SDK and Toolchain: Choosing the Correct Build Tool

The SDK and toolchain can produce incompatible packages when the branch, target, or ABI differs. Always use the tool that matches the target firmware.

SDK, toolchain, and build system

These concepts are related but different:

• Build system: the complete OpenWrt build environment. It can create the toolchain, kernel, root filesystem, packages, and firmware image.
• Toolchain: the compiler and cross-compilation tools used to build for the target architecture, such as ARM or MIPS rather than the build computer's CPU.
• SDK: a smaller environment normally used to compile external packages for a known firmware target.

The SDK is useful when you need to build an individual package without rebuilding the entire firmware.

Which tool should you use?

Download the correct SDK

The SDK must match at least:

• OpenWrt version or branch.
• Target and subtarget.
• CPU architecture.
• ABI and toolchain.

Start at:

1

https://downloads.openwrt.org/

Do not use an SDK from another target simply because the package looks simple. An ABI mismatch may appear only when the package is installed or executed on the router.

Prepare the package source

Get a package from the OpenWrt source tree:

1
2

git clone https://github.com/openwrt/openwrt.git
cd openwrt

For a downloaded SDK archive:

1
2
3

mkdir -p ~/openwrt-sdk
# Extract the SDK archive into this directory.
cd ~/openwrt-sdk/openwrt-sdk-*/

The directory layout can vary. Check that it contains Makefile, include/, and the required package directories.

Update SDK feeds

Some packages require feeds:

1
2

./scripts/feeds update -a
./scripts/feeds install -a

If a package is in a source checkout, verify its path before building. Do not copy a package from another branch without checking dependencies and APIs.

Select the target

Open configuration:

1

make menuconfig

Select the correct target architecture and the options required by the package. Even when the SDK is released for a fixed target, read its configuration information to avoid choosing the wrong variant.

Generate defaults if needed:

1

make defconfig

Build a package

For a package in package/aiot/hello/:

1

make package/aiot/hello/compile V=s

The package path may be different in another tree. Locate its Makefile and adjust the command.

Build all selected packages:

1

make package/compile V=s

The resulting .ipk files are normally placed under bin/packages/ or the corresponding output directory.

Test the package on a router

Check the router architecture and dependencies:

1

opkg print-architecture

Copy and install the package:

1
2
3

scp ./bin/packages/<feed>/<arch>/<package>.ipk root@<router-ip>:/tmp/
ssh root@<router-ip>
opkg install /tmp/<package>.ipk

Use a package only on a router with a compatible target and ABI. If opkg reports a missing dependency, do not force the installation unless you understand the consequences.

Where is the toolchain?

When building OpenWrt from source, the toolchain is created inside the build tree and used for the selected target. Beginners normally do not need to call the compiler directly; OpenWrt's Makefiles set the environment and compiler flags.

Verbose output helps inspect the compiler, sysroot, CFLAGS, and staging paths:

1

make V=s package/aiot/hello/compile

Do not substitute an arbitrary system compiler for the OpenWrt toolchain.

Common errors

Exec format error

The package was probably built for the wrong CPU architecture.

cannot find -l...

A dependency or development library is missing from the staging directory.

Kernel too old or symbol errors

The package may have been built for a different branch or kernel than the firmware.

The package installs but does not run

Check ABI, dynamic linker, execute permissions, runtime dependencies, and the service log on the router.

Compatibility checklist

Before distributing a package:

• The OpenWrt branch matches the target firmware.
• Target and subtarget are correct.
• Architecture and ABI are correct.
• Dependencies are declared in the Makefile.
• The package was tested on the matching router or image.
• No secret, token, or build-machine path is included.

Official sources

• OpenWrt — Using the SDK
• OpenWrt — Build system essentials
• OpenWrt — Using build environments
• OpenWrt source repository