Setting Up the OpenWRT Build Environment

Prerequisites and Host Machine Setup (Ubuntu/Debian)

1. Install necessary libraries

   sudo apt-get update
   sudo apt-get install build-essential clang flex bison g++ gawk gcc-multilib g++-multilib gettext git libncurses5-dev libssl-dev python3-setuptools rsync swig unzip zlib1g-dev file wget

2. Install QEMU

   sudo apt-get install qemu-system

Downloading the OpenWRT Source (Git)

Clone OpenWRT repository to your system

If you are using SSH:

git clone git@github.com:openwrt/openwrt.git

If you are using HTTPS:

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

Directory Structure of the Source Tree

This is the general directory structure for the source:

• /config : configuration files for menuconfig
• /include : makefile configuration files
• /package : packages makefile and configuration
• /scripts : miscellaneous scripts used throughout the build process
• /target : makefile and configuration for building imagebuilder, kernel, sdk and the toolchain built by buildroot.
• /toolchain : makefile and configuration for building the toolchain
• /tools : miscellaneous tools used throughout the build process

Understanding Feeds and Package Sources

Feeds

• A feed is a collection of packages that are grouped together based on a common theme or category.
• Feeds are used to organize packages in a way that makes it easy to manage and update them.
• OpenWRT comes with several pre-defined feeds, including:
  • kernel: kernel packages
  • base: base system packages
  • luci: web interface packages
  • packages: general-purpose packages
  • telephony: telephony-related packages
  • telephony/luci: telephony-related luci packages

Package Sources

• A package source is a repository of packages that can be used by OpenWRT to install packages.
• Package sources are typically hosted on a remote server and can be accessed using a URL.
• OpenWRT comes with several pre-defined package sources.

Configuring Feeds and Package Sources

• To configure feeds and package sources in OpenWRT, you need to edit the feeds.conf file.
• The feeds.conf file is located in the feeds directory of the OpenWRT source tree.
• In the feeds.conf file, you can specify which feeds to include and which package sources to use.

Update & Install feeds

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

Example feeds.conf File

src-github-packages https://github.com/openwrt/packages.git
src-git luci https://git.openwrt.org/project/luci.git
src-git telephony https://git.openwrt.org/project/telephony.git

In the above example, the feeds.conf file includes three feeds:

• src-github-packages: a feed that includes packages from the OpenWRT GitHub repository
• src-git luci: a feed that includes packages from the Luci repository
• src-git telephony: a feed that includes packages from the Telephony repository

Selecting and Configuring a Target (make menuconfig)

• Run the command make menuconfig

A menu screen will appear, allowing you to configure the system.

Configure the Target Device

• Once you have selected the target device, you can configure it by navigating through the various sections of the menuconfig interface. Some of the key sections include:
  • General Settings: Configure the general settings of the target device, such as the kernel version and the device name.
  • Kernel: Configure the kernel settings, such as the kernel version and the kernel configuration.
  • Bootloader: Configure the bootloader settings, such as the bootloader version and the bootloader configuration.
  • Network: Configure the network settings, such as the network interface and the network protocol.
  • Base System: Configure the base system settings, such as the package selection and the package configuration.

Save and Exit

• Once you have configured the target device, save the changes by exiting the menuconfig interface.
• The changes will be saved to the .config file.

Building the Image

Building an OpenWRT image can be a time-consuming process, but it can be significantly accelerated by using multiple processor cores.

• Using the -j Option

  • To build the image using multiple processor cores, you can use the -j option with the make command.

  • The -j option specifies the number of jobs to run in parallel.

    Example: Building with 4 Processor Cores To build the image using 4 processor cores, you can use the following command:

    make j4 V=s

    This will instruct the make command to use 4 processor cores to build the image.

  • Using Multiple Cores Can Increase Build Speed

    Using multiple processor cores can significantly increase the build speed of the OpenWRT image. However, it’s essential to note that using too many cores can actually decrease the build speed due to increased memory usage and context switching.

• Using the V option

  • Use make V=s for a Quieter Build

    When building the image, you can use the V=s option to suppress verbose output. This can make the build process quieter and more efficient.

    make V=s

    This will instruct the make command to suppress verbose output, making the build process quieter and more efficient.

Image Types and Their Use (sysupgrade, initramfs, factory)

sysupgrade Image

• Purpose: Upgrade the existing OpenWRT installation on the device.
• Description: sysupgrade images are used to upgrade the existing OpenWRT installation on the device. They contain the new firmware and configuration files.
• Requirements: The device must have an existing OpenWRT installation and a compatible kernel version.

initramfs Image

• Purpose: Boot the device with a minimal kernel and root filesystem.
• Description: initramfs images are used to boot the device with a minimal kernel and root filesystem. They are typically used for troubleshooting or debugging purposes.
• Requirements: The device must have a compatible kernel version and a bootable initramfs image.

factory Image

• Purpose: Restore the device to its factory default settings.
• Description: factory images are used to restore the device to its factory default settings. They contain the original firmware and configuration files.
• Requirements: The device must be in a state where it can be restored to its factory default settings.

sysupgrade-kernel Image

• Purpose: Upgrade the kernel of the existing OpenWRT installation on the device.
• Description: sysupgrade-kernel images are used to upgrade the kernel of the existing OpenWRT installation on the device. They contain the new kernel and configuration files.
• Requirements: The device must have an existing OpenWRT installation and a compatible kernel version.

sysupgrade-rootfs Image

• Purpose: Upgrade the root filesystem of the existing OpenWRT installation on the device.
• Description: sysupgrade-rootfs images are used to upgrade the root filesystem of the existing OpenWRT installation on the device. They contain the new root filesystem and configuration files.
• Requirements: The device must have an existing OpenWRT installation and a compatible root filesystem.

Troubleshooting Build Errors

Missing Dependencies

• Error: “Missing dependency: <package_name>”
• Solution: Install the missing dependency using the make command with the install option: make install <package_name>

Compiler Errors

• Error: “Compiler error: <error_message>”
• Solution: Check the compiler version and configuration. Ensure that the compiler is up-to-date and configured correctly.
• Additional Solution: Try rebuilding the package with a different compiler or configuration.

Library Issues

• Error: “Library issue: <error_message>”
• Solution: Check the library versions and configuration. Ensure that the libraries are up-to-date and configured correctly.
• Additional Solution: Try rebuilding the package with a different library version or configuration.

Build System Errors

• Error: “Build system error: <error_message>”
• Solution: Check the build system configuration and environment. Ensure that the build system is correctly configured and the environment is set up properly.
• Additional Solution: Try rebuilding the package with a different build system or configuration.

Package Errors

• Error: “Package error: <error_message>”
• Solution: Check the package configuration and dependencies. Ensure that the package is correctly configured and the dependencies are met.
• Additional Solution: Try rebuilding the package with a different configuration or dependencies.

Missing Files

• Error: “Missing file: <file_name>”
• Solution: Check the file system and ensure that the missing file exists and is correctly configured.
• Additional Solution: Try rebuilding the package with a different file system or configuration.

Version Conflicts

• Error: “Version conflict: <package_name> ”
• Solution: Check the package versions and configuration. Ensure that the package versions are compatible and correctly configured.
• Additional Solution: Try rebuilding the package with a different version or configuration.