OpenWrt is a highly extensible, Linux-based operating system tailored for embedded networking devices. Unlike vendor-supplied firmware, it offers a fully writable filesystem and a package management system, allowing users to customize their devices extensively. This guide outlines the process of setting up a build environment and compiling a custom OpenWrt image.

System Prerequisites

A Linux environment is required for the build process. Ubuntu 22.04 LTS (64-bit) is a recommneded distribution. The compilation process requires significant disk space; a minimum of 10GB is necessary, though allocating 20GB or more is advisable to accommodate source code, toolchains, and multiple build outputs.

Step 1: Obtain the Source Code

Clone the official OpenWrt repository from Git. This process may take some time depanding on network latency.

git clone https://git.openwrt.org/openwrt/openwrt.git
cd openwrt

Step 2: Install Build Dependencies

Before compiling, the host system must have the necessary development tools and libraries. While the build system will prompt for missing dependenceis, it is efficient to install the core packages beforehand.

sudo apt update
sudo apt install -y build-essential gcc g++ make cmake \
libncurses5-dev openssl libssl-dev wget git curl \
python3 python3-dev python3-distutils perl unzip \
zlib1g-dev gawk subversion

Step 3: Update Package Feeds

OpenWrt uses "feeds" to manage additional packages. Update and install all available feeds to ensure access to the full package repository.

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

Step 4: Configuration

Run the configuration menu to select the target platform and specific packages.

make menuconfig

This interface allows you to define:

• Target System: The specific hardware architecture (e.g., Qualcomm Atheros, Broadcom).
• Subtarget: The specific chipset family.
• Target Profile: The exact router model.
• Global Build Settings: Options like enabling IPv6 or removing unwanted features to reduce image size.

Step 5: Compiling the Image

Initiate the build process. The -j flag specifies the number of parallel jobs, which significantly speeds up compilation on multi-core CPUs. The V=s flag increases verbosity, which is helpful for diagnosing errors.

make -j$(nproc) V=s

If the build fails due to missing dependencies, the error log usually indicates the required package. Install it and re-run the command. For network issues causing download failures, you can manually place the source tarballs into the dl/ directory.

Step 6: Locating the Output

Upon successful compilation, the firmware binaries are located in the bin/targets/ directory, structured by the chosen target platform.

ls bin/targets/[target]/[subtarget]/

Firmware Image Types

Several files are generated during the build. Understanding their purpose is crucial for correct installation.

Manual Upgrade via CLI

If the device is already running OpenWrt, you can upgrade the firmware via the command line. Transfer the sysupgrade.bin file to the /tmp directory (which resides in RAM) and execute the upgrade command.

sysupgrade /tmp/openwrt-*-sysupgrade.bin