Skip to content

CLAUDE.md

Latest commit

 

History

History
62 lines (46 loc) · 2.82 KB

CLAUDE.md

File metadata and controls

62 lines (46 loc) · 2.82 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains GitHub Actions workflows for building custom OpenWRT firmware images with additional packages (Passwall, Argon theme). It supports multiple OpenWRT versions and architectures.

Key Architecture

Version Compatibility

  • OpenWRT 24.x: Uses opkg package manager with .ipk files
  • OpenWRT 25.x: Uses apk package manager with .apk files
  • Version detection pattern: [[ "$VERSION" == 24.* ]] or [[ "$VERSION" == 25.* ]]

Build Pipeline (build_image_all.yml)

  1. build_passwall - Builds Passwall (requires Go installation)
  2. build_theme_argon - Builds Argon theme
  3. build_image - Combines artifacts and creates final firmware image

Jobs run in parallel where possible; build_image depends on all package builds.

Build Environment

  • Package builds run in debian:13 (trixie) containers; the OpenWrt SDK tarball is downloaded from downloads.openwrt.org and unpacked to /builder by each job's Prepare step (recreating the /builder + buildbot user layout the official SDK images had)
  • build_image downloads the ImageBuilder tarball on the host and runs build_image.sh in a debian:13 container with the unpacked tree bind-mounted at /builder
  • The official openwrt/sdk / openwrt/imagebuilder Docker images are no longer used: they are based on Debian bullseye, whose apt security repo was retired when bullseye LTS ended 2026-08-31, breaking every job's apt-get update
  • Version discovery in the setup job parses the releases index at downloads.openwrt.org (no Docker Hub tag queries)

Supported Targets

  • Architectures: x86-64, rockchip-armv8, mediatek-filogic (25.12+ only — the nradio profile was merged upstream after the 24.10 branch, so the setup job excludes filogic from the 24.10 matrix line)
  • Profiles: generic (x86-64), friendlyarm_nanopi-r2s (rockchip-armv8), nradio_c8-668gl (mediatek-filogic; official upstream device support — no custom DTS/patches needed)

Build Scripts

build_image.sh

Creates final firmware image. Key environment variables:

  • PROFILE - Device profile name
  • PACKAGES - Space-separated package list
  • ROOTFS_SIZE / KERNEL_SIZE - Partition sizes
  • ARCH / VERSION - Target architecture and OpenWRT version

For OpenWRT 25.x, uses ADD_LOCAL_KEY=1 to allow unsigned custom packages.

Important Patterns

Package Extension Handling

if [[ "${{ matrix.version }}" == 24.* ]]; then
  echo "PKG_EXT=ipk" >> $GITHUB_ENV
else
  echo "PKG_EXT=apk" >> $GITHUB_ENV
fi

Artifact Retention

  • Intermediate packages: 7 days
  • Final firmware images: 30 days

Workflow Triggers

  • Push to master branch
  • Manual dispatch (workflow_dispatch)
  • Daily schedule at 21:00 UTC