Common Compilation Errors in OpenWrt: Solutions and Tips

OpenWrt is an open-source embedded operating system. As more routers support flashing, we often compile the corresponding firmware to add the features we want. During the compilation process, we may encounter some compilation errors. If you are a beginner, these issues may leave you feeling confused. To help more people learn to compile OpenWrt firmware, this article summarizes common compilation errors and provides solutions. Overall, compiling OpenWrt is quite easy as long as you have basic Linux command operation skills, so there is no need for a development background.

Types of Compilation Errors

First, let’s categorize the compilation issues, which mainly fall into the following categories:

System Issues

It is recommended to compile using Ubuntu Linux. Typically, we install the Ubuntu system through a virtual machine and compile within the virtual machine. To ensure that the compilation environment is stable, it is advisable to use an Ubuntu version close to the OpenWrt release date, to avoid issues with tool versions. However, do not pursue the latest version of Ubuntu; a version released 2-3 years before OpenWrt is the most suitable.

You can download the Ubuntu image from the Alibaba Cloud mirror website:

https://developer.aliyun.com/mirror/

Tool Issues

Before compiling OpenWrt, you need to install some common packages in Linux (using Ubuntu as an example). These tools play different roles during compilation, such as downloading source code and packaging images. If the tools are incomplete, it can lead to compilation errors. You can install all required tools using the following command, and of course, if you encounter a missing tool, you can install it separately.

sudo apt update -y
sudo apt install -y cmake curl wget vim git antlr3 asciidoc autoconf automake autopoint binutils bison  
build-essential bzip2 ccache  cpio  device-tree-compiler fastjar flex gawk gettext gcc-multilib g++-multilib 
 gperf haveged help2man intltool libc6-dev-i386 libelf-dev libglib2.0-dev libgmp3-dev libltdl-dev 
libmpc-dev libmpfr-dev libncurses5-dev libncursesw5-dev libreadline-dev libssl-dev libtool lrzsz 
mkisofs msmtp nano ninja-build p7zip p7zip-full patch pkgconf python2.7 python3 python3-pyelftools 
libpython3-dev qemu-utils rsync scons squashfs-tools subversion swig texinfo uglifyjs upx-ucl unzip 
xmlto xxd zlib1g-dev ack

Error Examples

If you have not installed the compiler or other tools, you may encounter similar errors when updating feeds, prompting you to install g++, ncurses, etc. The solution is to install the corresponding tools first, for example, to install ncurses:

sudo apt install -y libncurses5-dev libncursesw5-dev

Checking 'ldconfig-stub'... ok.

Build dependency: Please install the GNU C++ Compiler (g++) 6 or later
Build dependency: Please reinstall the GNU C++ Compiler (6 or later) - it appears to be broken
Build dependency: Please install ncurses. (Missing libncurses.so or ncurses.h)

Prerequisite check failed. Use FORCE=1 to override.
make: *** [/home/test/openwrt/include/toplevel.mk:182: /home/test/openwrt/staging_dir/host/.prereq-build] Error 1
Collecting package info: feeds/packages/lang/python/python-parsley^Cmake: *** wait: No child processes.  Stop.
make: *** Waiting for unfinished jobs....
make: *** wait: No child processes.  Stop.

Network Issues

Network issues are probably the main problems when compiling OpenWrt. In domestic environments, you often encounter slow access speeds or inability to access certain resources, as many foreign websites are blocked.

1. Downloading OpenWrt Source Code

We first need to clone the OpenWrt source code using the git command. Beginners might be discouraged right away, as the following errors often occur:

Download error log:

error: RPC failed; curl 56 GnuTLS recv error (-54): Error in the pull function.
fatal: the remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

A successful download should look like this:

test@test:~$ git clone https://github.com/openwrt/openwrt.git
Cloning into 'openwrt'...
remote: Enumerating objects: 653141, done.
remote: Counting objects: 100% (258/258), done.
remote: Compressing objects: 100% (215/215), done.
remote: Total 653141 (delta 100), reused 143 (delta 41), pack-reused 652883
Receiving objects: 100% (653141/653141), 243.35 MiB | 5.61 MiB/s, done.
Resolving deltas: 100% (437100/437100), done.

1. Downloading dl packages

Error log:

SHELL= flock /home/test/openwrt/tmp/.xz-5.4.3.tar.bz2.flock -c '   /home/test/openwrt/scripts/download.pl "/home/test/openwrt/dl" "xz-5.4.3.tar.bz2" "9243a04598d7a70c1f567a0143a255581ac5c64b140fd55fd5cbc1e00b0e6f90" "" "@SF/lzmautils" "http://tukaani.org/xz"    '
Copyright(C) Derry(ttcoder.cn)
+ curl -f --connect-timeout 20 --retry 5 --location https://downloads.sourceforge.net/lzmautils/xz-5.4.3.tar.bz2
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:--  0:00:20 --:--:--  0
curl: (28) Connection timed out after 20004 milliseconds
Warning: Transient problem: timeout Will retry in 1 seconds. 5 retries left.
  0     0    0     0    0     0      0      0 --:--:--  0:00:20 --:--:--  0
curl: (28) Connection timed out after 20002 milliseconds
Warning: Transient problem: timeout Will retry in 2 seconds. 4 retries left.
  0     0    0     0    0     0      0      0 --:--:--  0:00:20 --:--:--  0
curl: (28) Connection timed out after 20004 milliseconds
Warning: Transient problem: timeout Will retry in 4 seconds. 3 retries left.

If you see messages like timeout Will retry in 1 seconds. 5 retries left, it indicates poor network conditions. You can try downloading the dl package first to check if the network is functioning properly. Note that having a working network does not only refer to being able to access domestic websites such as Baidu or Sina, but also to accessing the necessary resource websites. For example, if the resource URL is https://downloads.sourceforge.net/lzmautils/xz-5.4.3.tar.bz2, you can manually check if you can access it using the wget command:

wget https://downloads.sourceforge.net/lzmautils/xz-5.4.3.tar.bz2

If you cannot access it, you may need to switch your compilation machine’s network or set up a proxy. If you don’t have access to a proxy, you can also download the resource from another machine and place it in the dl directory or try using a mobile hotspot, as different ISPs may impose access restrictions on certain resources. This solution applies to all network issues during compilation.

Permission Issues

Root User Issues
It is not recommended to compile OpenWrt as the root user. If you compile as the root user, you may encounter the error configure: error: you should not run configure as root. The detailed error log is as follows:

checking for mkfifo... yes
checking whether mkfifo rejects trailing slashes... yes
checking whether mkfifoat rejects trailing slashes... yes
checking whether mknod can create fifo without root privileges... configure: error: in `/home/test/openwrt/build_dir/host/tar-1.34':
Copyright(C) Derry(ttcoder.cn)
configure: error: you should not run configure as root (set FORCE_UNSAFE_CONFIGURE=1 in environment to bypass this check)
See `config.log' for more details
make[3]: *** [Makefile:36: /home/test/openwrt/build_dir/host/tar-1.34/.configured] Error 1
make[3]: Leaving directory '/home/test/openwrt/tools/tar'
time: tools/tar/compile#8.80#3.90#24.21
    ERROR: tools/tar failed to build.
make[2]: *** [tools/Makefile:226: tools/tar/compile] Error 1
make[2]: Leaving directory '/home/test/openwrt'
make[1]: *** [tools/Makefile:222: /home/test/openwrt/staging_dir/host/stamp/.tools_compile_nyyynyynnnyyynynyyyyyyynyyynyynyynnynnyyyyyyyyyyyyyyyyynynyyyyyy] Error 2
make[1]: Leaving directory '/home/test/openwrt'
make: *** [/home/test/openwrt/include/toplevel.mk:232: world] Error 2

There are two solutions:

• Set Environment Variable

Set the environment variable FORCE_UNSAFE_CONFIGURE to 1 to bypass the root check: export FORCE_UNSAFE_CONFIGURE=1

• Switch to a Normal User for Compilation

Note that if you switch to a normal user directly, you may encounter permission issues because some files have already been generated by the root user. Therefore, you need to change the permissions for the entire project before switching by executing the command chmod 777 ./ -R in the OpenWrt source root directory.

Multi-core Compilation Issues

When compiling OpenWrt, we can use make V=s -j$corenum for multi-core compilation, where $corenum is the number of CPU cores used for compilation. Multi-core compilation can improve compilation speed. However, if you are compiling OpenWrt source code for the first time using multi-core compilation, you will definitely encounter compilation errors, and the error logs may not clearly indicate the cause. When encountering strange compilation issues, directly use make V=s for single-core compilation to see clear error logs. It is important not to use multi-core compilation for the first compilation; only after the entire system has been compiled can you use multi-core for subsequent compilations.

Storage Space Issues

During compilation, you may encounter errors like no space. This is because the compilation machine has run out of disk space. You generally need to reserve more than 30GB of space for OpenWrt compilation.

Conclusion

Among the issues mentioned above, the most difficult to resolve is the network issue. If there are no network problems, anyone who can install Linux can complete the compilation. Here are some additional compilation tips:

• When there is no external network, you can connect using a mobile hotspot; generally, data networks can smoothly access resources like GitHub.
• You can rent a cloud server for compilation, as there are no network issues on cloud servers. You can rent the server based on usage duration and download third-party packages to your local environment after compilation.
• If you only encounter issues downloading the OpenWrt framework source code, you can search for related clone repositories on Gitee.
• If you only want to add some plugins, you might consider using the existing OpenWrt SDK to package the firmware, which is faster and less dependent on network access. You can also consider cloud compilation of OpenWrt, as there are related tutorials available online.

OpenWrt is a fantastic embedded Linux project. Through OpenWrt, you can conveniently learn about Linux, including Linux system architecture, Linux kernel, Linux messaging mechanisms, Linux image packaging, and Linux drivers. It is suitable for users of different technical levels. You only need a home router to start learning embedded Linux.

Of course, compilation is just the first step. I hope that the above summary of compilation errors will help everyone avoid being troubled by compilation errors.