Skip to content

Build from source

Anyone can rebuild a release. The repository holds only build configuration, patches and the rootfs overlay: no firmware binaries and no package source. Packages are fetched from their upstream feeds at build time, every one pinned to a commit.

Repository layout

The firmware repository pins several smaller repositories, listed with their documentation on the Repositories page. This is the layout of the firmware repository itself:

Path What it is
configs/arcadyan_aw1000.seed the package selection and image identity
configs/local-packages.pin out-of-feed packages, pinned to a commit
configs/license-overrides.tsv licences for packages that record none
feeds.conf.default every feed, pinned to a commit
feeds-src/cwfeed/ the vendored feed (qBittorrent stack, AdGuard Home app, Syncthing app)
files/ the rootfs overlay (first-boot scripts, defaults, banner)
patches/feeds/ patches applied to the pinned feeds, with zero fuzz
patches/tree/ patches applied to files the OpenWrt tree carries itself (packages, build system), with zero fuzz
tools/ the build script and its helpers
docker/Dockerfile the pinned build environment
.github/workflows/ the checks and the build

On GitHub Actions

The build needs nothing but the repository.

Workflow When What it does
check every push and pull request shell syntax, the version label, that the pins resolve, and a config check: feeds, patches, pins, defconfig and the seed checks, without compiling
build by hand (Actions → build → Run workflow) or when a tag v<version> is pushed builds the image in the Docker environment, with a download cache and a compiler cache

The inputs of a manual run:

Input Default Meaning
clean off rebuild every package
opt_artifacts off also compile and verify the optional cw-opt feed
artifacts off upload the images as a workflow artifact (public for a public repository)

A job is limited to six hours by GitHub. A cold build takes roughly two hours; later builds are shorter because of the caches.

A tag v<version> is built by the same workflow, and its images go straight into a draft release: nothing is public and the site is not touched until that draft is published by hand.

Locally

You need a Linux machine (or a Linux VM) and Docker.

git clone --depth 1 --branch v25.12.5 https://github.com/openwrt/openwrt.git openwrt
docker build -t cleanwrt-builder docker/
docker run --rm \
  -v "$PWD/openwrt":/build -v "$PWD/cleanwrt-aw1000":/cleanwrt \
  cleanwrt-builder /cleanwrt/tools/cw-release-build.sh /build --clean

The sysupgrade image and a provenance bundle land in openwrt/bin/targets/qualcommax/ipq807x/.

Check first, compile later

CW_CHECK_ONLY=1 runs the feed, patch, pin, defconfig and seed checks and stops before compiling. Pass it with -e CW_CHECK_ONLY=1 to docker run. It takes a few minutes and catches almost every configuration mistake.

What the build script guarantees

tools/cw-release-build.sh applies the overlay, the pinned feeds and the patches (to the feeds and to the tree), then runs the mandatory post-defconfig fixups, and it fails rather than ship something stale:

  • the OpenWrt tree must be exactly at v25.12.5;
  • the version label in the seed and in the script must agree;
  • every feed and every local package must match its pinned commit;
  • a feed or tree patch that no longer applies cleanly fails the build, because the upstream code changed;
  • every package the seed selects must survive make defconfig;
  • init scripts must be executable and use procd correctly;
  • the image must fit the flash layout (UBI_PEBS ... line) and the size gate;
  • the kernel modules repository the image points at must have the vermagic of the built kernel;
  • the finished release is verified before it is called OK (tools/cw-check-image.sh): the three images present and non-empty, sha256sums matching the files on disk, the version label and device in the config that was built, the provenance bundle complete, the manifest carrying the selected packages, and the tree signing with the key the devices trust.

Signing

Key Purpose How
image signing (usign) signs every image tools/cw-sign-keys.sh --generate <tree> creates keys-release/. Never commit it. The build uses it when present.
apk key the key every image trusts and the one that signs the optional cw-opt feed one fixed pair: the public half is committed at files/etc/apk/keys/public-key.pem and ships in the overlay; the private half is the repository secret APK_PRIVATE_KEY (and keys-release/private-key.pem for a local release build), never committed. The build writes it to <tree>/private-key.pem, and tools/cw-check-release-keys.sh proves the two halves match.

A tree with no key lets OpenWrt generate one during the build, so every image carried a different /etc/apk/keys/public-key.pem and a device could no longer verify the cw-opt feed built from the same source. The patch in patches/tree/ removes a second build-to-build change: apk mkpkg stamps the build's own clock into every package, because a shallow clone has no per-package git history to take a date from, so /lib/apk/db/installed recorded a different checksum for every package in every image. Running mkpkg with a fixed epoch is the change upstream OpenWrt made; a package's own source date still sets its SourceDateEpoch, and rootfs timestamps are normalised as before, so nothing on the device changes.

On GitHub Actions these keys come from the repository secrets APK_PRIVATE_KEY, USIGN_KEY_BUILD and USIGN_KEY_BUILD_PUB. Without them the images are unsigned and the cw-opt feed stays disabled.

What this build changes upstream

Every patch this repository applies to someone else's code, and what each one is for. They are applied with patch -p1 at zero fuzz: a patch that does not apply cleanly fails the build rather than shipping a half-applied change.

The QModem feed

patch what it changes
0002-quectel-cm-ipv6-optional IPv6 gets its own retry ladder — 60 seconds, doubling, capped at 32 minutes — so a failed IPv6 setup no longer tears down the IPv4 call
0003-ndisc6-source-mirror the source mirror, because the original host answers 410 Gone
0004-sip-inbound-answer-delivered an inbound INVITE now carries a transaction-completion callback, so the LAN's 200 OK reaches the answer handler and the 2xx is ACKed as RFC 3261 requires. It also fixes a use-after-free that segfaulted the service
0005-sip-dialog-bye-both-directions the BYE is built as UAC or UAS depending on which side opened the dialog, and an in-dialog BYE is authenticated by the dialog's identity rather than challenged. A hang-up on the cellular side now tears the LAN leg down
0006-sip-cancel-unanswered-lan-invite a LAN INVITE that the handset, the machine or the page took is CANCELed, and the resulting 487 is consumed as the CANCEL's answer instead of being read as a failed call
0007-sip-inbound-credentials-from-uci /etc/config/qmodem_sip becomes the record of the inbound credential, and the runtime file under /var/run is derived from it at start and on reload
0008-sip-default-config-for-the-phone-bridge the defaults this router needs: the media socket pointed at the phone daemon, the inbound direction on, the account named awvoice, the password shared with the Wi-Fi key, and the vendor engine's own path switched off
0009-sip-voip-default-migration a first-boot script that migrates a configuration that still pointed at the vendor engine — and only when the media socket is the phone daemon's, so a hand-configured router is left alone
0010-qmi-wwan-nss-path-behind-its-own-guard restores the vendor-deleted CONFIG_RMNET_DATA guard. Without it modpost fails on a symbol this tree does not carry and the driver cannot be packaged at all

The LuCI feed

patch what it changes
0001-status-firmware-version-drop-luci-suffix the Firmware Version row shows the release description alone. A detached-HEAD feed was stamping "LuCI (HEAD detached at …)" into a user-facing page
0006-p910nd-menu-title-printer-server the menu title, from p910nd - Printer server to Printer server
0007-upgrade-check-cdn-no-asu the newer-version notice: the wording says CleanWRT, the links point at this project's releases rather than the OpenWrt CDN, and the version feed is pr0luci.github.io/cleanwrt-aw1000/.versions.json
0008-p910nd-mdns-type-label the option label reads mDNS type
0009-filemanager-default-width the file manager's default width, 400 to 800

Other feeds, and the OpenWrt tree itself

patch what it changes
3ginfo/0002-3ginfo-executable-mode 3ginfo.sh gains its executable bit, because LuCI fs.execs it directly and a fresh boot could fail before the chmod script ran
3ginfo/0003-3ginfo-menu-title the menu title becomes 3gInfo-lite
3ginfo/0004-radio-telemetry-and-redesign the radio page and the collector behind it: one locked snapshot per request, serving cells per carrier, a neighbour table that scans itself, and five-second defaults
3ginfo/0005-radio-telemetry-executable radiodata.sh gains its executable bit, for the same reason 0002 exists: the page runs it through fs.exec, and patch alone does not carry the mode
diskman/0001-disk-manager-menu-rename-services-move Disk Manager moves from the System menu to Services, with its title and every internal link
passwall_packages/0001-dns2socks-naiveproxy-sources two upstream release assets that no longer exist: dns2socks carries its source in the package, naiveproxy points at a prebuilt version
tree/0001-apk-package-timestamps-zero apk mkpkg runs with a fixed epoch, so two builds of one commit produce identical images

Themes

patch what it changes
packages/luci-theme-footstrap/0001-login-page-carries-the-image-logo one line: the login page shows the CleanWRT logo where the theme prints the router's hostname. The image file lives outside the theme's own directory, so a theme update can neither overwrite it nor collide with the patch

Changing a patch or moving a pin

  • Move a feed pin: change the commit after the ^ in feeds.conf.default, then make sure every patch in patches/feeds/ still applies (the check workflow does this).
  • Re-port a patch: apply it to the new upstream by hand, regenerate it with diff -u, and keep the header that says what it changes and why.
  • Add a tree patch: put it in patches/tree/, with paths from the tree root (for example include/package-pack.mk). tools/cw-apply-feed-patches.sh reverses the tree patches before every feeds update and applies them again at the start of the build.