openwrt/docs/backporting-research.md

OpenWRT Package Backporting Guide

Overview

Backporting allows you to use a newer version of a package (from OpenWRT master or a newer release) on an older stable release (e.g., OpenWRT 21.02).

The Process

1. Prepare Build Environment

   • You need the SDK (Software Development Kit) for your Target version (the older version you are running).
   • Example: If using OpenWRT 21.02 on x86/64, download the OpenWRT 21.02 SDK for x86/64.

2. Locate Source Package

   • Find the package in the newer source tree (e.g., GitHub openwrt/packages repository, master branch).
   • Package definition consists of:
     • Makefile
     • patches/ (directory, if any)
     • files/ (directory, optional configuration files)

3. Copy to SDK

   • Copy the package directory from the source to your SDK's package/ directory.
   • Alternative: Add the newer feed to feeds.conf.default but pin it to a specific commit (more complex due to dependencies). Manual copy is often easier for single packages.

4. Adjust Dependencies

   • Check DEPENDS line in Makefile.
   • Older SDKs might have older libraries.
   • If dependency is missing: You must backport the dependency package too.
   • If dependency is tool old: You might need to relax the requirement or backport the library (risky).

5. Build

   • Run make menuconfig and select the package.
   • Run make package/refined-package/compile.

Example: Backporting elinks

Scenario: Backporting elinks from Master to OpenWRT 21.02.

1. Get 21.02 SDK:

wget https://downloads.openwrt.org/releases/21.02.7/targets/x86/64/openwrt-sdk-21.02.7-x86-64_gcc-8.4.0_musl.Linux-x86_64.tar.xz
tar xJsOf openwrt-sdk-*.tar.xz
cd openwrt-sdk-*

2. Get elinks from Master: You don't need the whole master repo, just the folder.

svn export https://github.com/openwrt/packages/trunk/net/elinks package/elinks
# OR strictly from git
git clone https://github.com/openwrt/packages.git /tmp/packages
cp -r /tmp/packages/net/elinks package/

3. Check Makefile (package/elinks/Makefile):

PKG_NAME:=elinks
PKG_VERSION:=0.16.1.1  # Newer version
...
DEPENDS:=+libopenssl +libexpat ...

Verification: Check if libopenssl and libexpat are functional in your SDK. Usually they are standard.

4. Build:

./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig
# Select Network -> Web Servers/Browsers -> elinks
make package/elinks/compile V=s

5. Result: The new IPK will be in bin/packages/x86_64/base/elinks_*.ipk.

Common Pitfalls

• Kernel Dependencies: Kmods are hard to backport (require kernel version match). Avoid backporting kernel modules if possible.
• Library ABIs: If a package needs libfoo.so.2 but your system has libfoo.so.1, you need to backport the library, which might break other things. Static linking can sometimes solve this.