openwrt-build-helper/README.md

# OpenWrt Build Helper Scripts

## Overview
This repository contains shell scripts that streamline preparing, configuring, and building OpenWrt from source on Debian/Ubuntu systems (x86_64 and ARM64). It also includes convenience utilities to manage package selections, fetch device config.buildinfo, apply a DAHDI driver patch, and add external LuCI packages.

## What’s included
- prepare-openwrt-env.sh
  - Installs required build dependencies via apt on Ubuntu 22.04/24.04/26.04 and Debian 12/13+.
  - Handles x86_64 and ARM64 differences (Python/distutils, multilib notes, Go on ARM64).
- prepare-openwrt.sh
  - Clones or updates the OpenWrt source repo in the top-level `openwrt/` root.
  - Lets you select Stable, Beta, or Snapshot versions interactively.
  - Uses the script location as the source of truth, so running it from another current working directory is supported.
  - On first run from a helper checkout, relocates that checkout to `openwrt/helper/`.
  - Updates feeds and runs make defconfig.
- add-external-repos.sh
  - Clones or updates additional package repositories into package/.
  - Currently includes luci-app-netspeedtest and luci-app-easytier (adjust REPOS as needed).
- download-config.sh
  - Downloads config.buildinfo for a selected device based on your checked-out OpenWrt version (stable or snapshot).
  - Writes .config and runs make defconfig.
  - Prints firmware URL and a Firmware Selector link for reference.
- add-openwrt-packages.sh
  - Enables packages listed in a text file by appending CONFIG_PACKAGE_<name>=y to .config (without removing existing settings).
  - Verifies presence in package/ or feeds/ and reports missing ones, then runs make defconfig.
- update-go-path.sh
  - Detects the latest Go installation under /usr/lib/go-* and sets CONFIG_GOLANG_EXTERNAL_BOOTSTRAP_ROOT in .config.
- apply-dahdi-patches.sh
  - Writes a DAHDI driver patch into package/feeds/telephony/dahdi-linux/patches/300-fix-dahdi-max-attempts.patch.
  - Fixes MAX macro naming collisions in multiple DAHDI modules for OpenWrt 24.10.4 builds.

## System requirements
- OS: Ubuntu 22.04/24.04/26.04 or Debian 12/13+ (others may work with adjustments)
- Architectures: x86_64/amd64 and aarch64/arm64
- Tools: git, wget, curl, bash
- Internet access for feeds and package downloads
- Optional: Go (required by some OpenWrt packages; auto-configured on ARM64 by prepare-openwrt-env.sh; configurable via update-go-path.sh)

## Quick start
1) Prepare the host machine
- Run: ./prepare-openwrt-env.sh
- This installs compilers, headers, Python tooling, and other build prerequisites.

2) Get OpenWrt sources
- Run: ./prepare-openwrt.sh
- Choose Stable, Beta, or Snapshot.
- The script:
  - Reuses or creates the top-level OpenWrt root at `./openwrt`.
  - Moves this helper checkout to `./openwrt/helper` on first run.
  - Updates/install feeds and runs make defconfig.

3) Add optional external packages
- From the OpenWrt root:
  - ./helper/add-external-repos.sh
- This pulls extra LuCI packages into package/.

4) Import a device config.buildinfo (optional but convenient)
- From the OpenWrt root:
  - ./helper/download-config.sh
- Pick a device, and the script writes .config and runs make defconfig.

5) Enable additional packages from a list (optional)
- Create a file packages.txt containing package names (whitespace or newlines).
- From the OpenWrt root:
  - ./helper/add-openwrt-packages.sh packages.txt

6) Configure Go bootstrap path (if needed)
- From the OpenWrt root:
  - ./helper/update-go-path.sh
- This sets CONFIG_GOLANG_EXTERNAL_BOOTSTRAP_ROOT to the latest /usr/lib/go-X.XX/ found.
- You can override it manually in .config if necessary.

7) Apply DAHDI patch (only if you build telephony/dahdi-linux)
- Ensure telephony feed is installed:
  - ./scripts/feeds update telephony
  - ./scripts/feeds install -a
- Then run:
  - ./helper/config_24.10.4/apply-dahdi-patches.sh
- Build the package:
  - make package/feeds/telephony/dahdi-linux/{clean,prepare} V=s
  - make package/feeds/telephony/dahdi-linux/compile V=s

8) Build OpenWrt
- Common commands:
  - make menuconfig
  - make -j$(nproc) download world
- Artifacts will be in bin/ after the build completes.

## Script usage notes and tips
- Run locations:
  - `prepare-openwrt.sh`: resolves paths from the script location, not your current shell directory.
  - `prepare-openwrt-env.sh`: can be run before the first normalization from the fresh helper checkout.
  - All other helper scripts: run them from inside the OpenWrt source root as `./helper/...` unless otherwise indicated.
- Feeds:
  - If a package can’t be found, ensure feeds are updated/installed:
    - ./scripts/feeds update -a && ./scripts/feeds install -a
- Go toolchain:
  - On x86_64, Go is optional unless your selection pulls packages needing Go (e.g., firewall4 in some versions). If needed:
    - sudo apt install golang -y
    - Then use update-go-path.sh to set .config automatically.
- ARM64 multilib:
  - The script installs cross multilib packages for better compatibility, but not all targets need them. If apt errors on specific multilib packages, remove or adjust as appropriate for your environment.

## Troubleshooting
- Telephony feed not found when applying DAHDI patch:
  - Run feeds update/install for telephony as shown above.
- Version detection in download-config.sh:
  - If you’re on a branch like openwrt-24.10, the script will try to find the latest v24.10.x tag automatically. Otherwise it prompts for a version (e.g., 24.10.4 or SNAPSHOT).
- Missing packages in add-openwrt-packages.sh:
  - Ensure the corresponding feed is enabled in feeds.conf.default and run feeds update/install.
- Permission errors:
  - Scripts use umask 022 and do not require root except when installing apt packages.
- Clean up and rebuild a package:
  - make package/<pkg>/{clean,compile} V=s
- Full rebuild:
  - make clean; make -j$(nproc) download world

## Directory behavior
- If you start from a freshly cloned helper checkout at `<parent>/<origin_folder>`, `prepare-openwrt.sh` will:
  - Reuse or create `<parent>/openwrt/` as the OpenWrt source root.
  - Move the entire helper checkout, including its `.git`, to `<parent>/openwrt/helper/`.
  - Initialize or update the OpenWrt source tree directly in `<parent>/openwrt/`.
- If you later rerun `openwrt/helper/prepare-openwrt.sh`, it reuses the parent `openwrt/` directory and does not move directories again.
- If the script is already located in a real OpenWrt source root, it treats that directory as the source root and does not relocate it just because the directory name is `openwrt`.

## Security and safety
- Scripts use set -e to stop on errors.
- They modify .config and write under package/ and feeds/ inside your OpenWrt tree.
- Backup your .config if you need a known baseline.

## License and authorship
- Scripts authored by Zhe Yuan with help from ChatGPT.
- License: MIT (unless you choose a different license; update this line accordingly).