OpenWrt Compilation Step-by-Step Command Explanation Tutorial

Introduction:

In this article, we will introduce the process of compiling OpenWrt from source code step-by-step and explain each command used in the process.
The process of compiling OpenWrt is like a tape recorder. Except for choosing system components, almost every compile involves copying and pasting the same commands. It is important to understand the purpose of each command and when to execute them in order to better solve problems encountered during compilation and to compile firmware more smoothly.

Before we start:

Before we begin, make sure that your computer meets the following requirements:

Linux system (Ubuntu LTS or Debian recommended)
At least 2 GB of RAM
At least 40 GB of disk space
Internet connection (Please make sure that you have a stable connection which is not blocked by firewall)

Step 1: Install Required Packages

⚠️ Do not use root account to build!
To compile OpenWrt, we need to install some required packages. Open a terminal and run the following command:

sudo apt update
sudo apt upgrade -y 
sudo apt-get install ack antlr3 asciidoc autoconf automake autopoint binutils bison build-essential bzip2 ccache cmake cpio curl device-tree-compiler fastjar flex gawk gettext gcc-multilib g++-multilib git 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 python3-pip libpython3-dev qemu-utils rsync scons squashfs-tools subversion swig texinfo uglifyjs upx-ucl unzip vim wget xmlto xxd zlib1g-dev

These packages will allow us to compile OpenWrt and its dependencies.

Step 2: Download and Install OpenWrt Source Code

Option 1. Download the latest OpenWrt source code from the official website (https://openwrt.org/downloads). Once downloaded, extract it to a directory of your choice, for example:

mkdir ~/openwrt
cd ~/openwrt
tar -xvzf ~/Downloads/OpenWrt-*.tar.gz --strip-components=1

Option 2: Lean’s source code:

git clone https://github.com/coolsnowwolf/lede openwrt

Option 3: Lienol’s source code:

git https://github.com/Lienol/openwrt openwrt

The source codes of the two big guys have their own advantages and disadvantages. The Lean one is more inclined to the original version, and the UI details of Lienol have been optimized. Pull the source code, choose one of the two.

Step 3: Download and Install Feeds

Enter the source code directory:

cd openwrt

Download the package source code in the feeds source:

./scripts/feeds update -a

Feeds are extended package, independent of the OpenWrt source code, so it needs to be pulled and updated separately.
Additional packages what you need to be added to the file feeds.conf.default before run the command.

Install packages from feeds:

./scripts/feeds install -a

Perhaps you would see some warnings. To make sure feeds install successfully you may need to run the command one more time.

Step 4: Configure OpenWrt

Before we can compile OpenWrt, we need to configure it based on our needs. Run the following command to open the configuration menu:

make menuconfig

This will open a menu where we can select which packages to include in the compilation. Choose the packages that you need and save the configuration.
If no package is adjusted or the file .config is missing, enter

make defconfig

it will detect the compilation environment and generate a default compilation configuration file.

Step 5: Build OpenWrt

Once the configuration is done, we can start the compilation process. Run the following command to start download the packages required for compilation:

make -j$(nproc) download

-j$(nproc) It refers to the use of threads to download and compile. In theory, the larger the number is faster, but there seems to be an upper limit. In fact, the speed of more than 5 threads is not much different.

We will check if all files were downloaded correctly:

find dl -size -1024c -exec ls -l {} \;

This command can list downloaded incomplete files. According to my experience if it is concluded that files smaller than 1k are incomplete downloads. If such files exist, you can use

find dl -size -1024c -exec rm -f {} \;

command to remove them, then re-run

make -j$(nproc) download

Downloading and checking repeatedly to confirm that all files are complete can greatly improve the success rate of compilation and avoid wasting time.

Start the compilation process:

make -j1 V=s

-j1 Use single-threaded compilation. It recommend single-threaded compilation at first time because metaphysical problems may have a high success rate, and it is convenient to view error logs.
Of cause you also can use multi-threaded compilation:

make -j$(($(nproc) + 1)) V=s

V=s: Output detailed logs, which are used to find errors when compilation fails. Moreover, the full-screen code can be pretended to be running, and it takes several hours to run, and the pretending is more durable.

Rebuild

If you want to build OpenWRT once more, then just simply use these commands:

cd openwrt
git pull
./scripts/feeds update -a
./scripts/feeds install -a
make defconfig
make -j$(nproc) download
make -j$(($(nproc) + 1)) V=s

If you need to re-configure packages:

rm -rf ./tmp && rm -rf .config
git pull
./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig
make -j$(nproc) download
make -j$(($(nproc) + 1)) V=s

⚠️ If you’re compiling with WSL or WSL2:
Since the PATH path of wsl contains Windows paths with spaces, compilation may fail. Please add
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
in front of the compilation commands.

File cleanup:
- Clear old compilation artifacts (optional)
```
make clean
```
  Execute after a large-scale update of the source code or a kernel update to ensure the compilation quality. This action will delete ./bin and ./build_dir files in the directory.
- Clear directories such as old compilation products, cross-compilation tools and toolchains (optional)
```
make dirclean
```
  It must be executed before changing the architecture and compiling. This action will delete./bin and ./build_dir files in the directory (make clean) as well as ./staging_dir, ./toolchain, ./tmp and ./logs files.
- Clean up files other than OpenWrt source (optional)
```
make distclean
```
  Unless you are doing development and plan to push to a remote warehouse like GitHub, it is almost useless. This operation is equivalent to make dirclean plus delete ./dl, ./feeds directory and .config file.
- Restore OpenWrt source code to original state (optional)
```
git clean -xdf
```
  If the source code is changed, or it has not been compiled for a long time, it will be used.
- clear temporary files
```
rm -rf tmp
```
  delete some temporary files generated by execution make menuconfig, including retrieval information of some software packages. Packages will be reloaded. If it is not deleted, some newly added software packages will not be displayed.
- Delete the compilation configuration file
```
rm -f .config
```
If some packages are deselected without deletion, their dependent components will not be automatically cancelled, so it is recommended to delete them when components need to be adjusted.
Special Usage
You can copy or create any files or folders to the directory openwrt/files. These files will be integrated to the corresponding directory in the firmware Linux OS. For example you create a file openwrt/files/etc/banner then you will find /etc/banner in your OpenWRT OS and the OS will show the banner when you logon. It is very convenient when you want to customize your system automatically.

Step 6: Install OpenWrt

Once the compilation is complete, we can install OpenWrt on our device. Please follow your device instruction to install your firmware.
The built firmware will be in bin/targets.

Conclusion:

That’s it! Now you know how to compile and install OpenWrt from source code. If you have any questions or issues, please leave a comment below.