OpenWrt 25

[ispyisail]

Hi team

Does this mean a major rewrite of gargoyle?

If so, is this a problem?

[Lantis]

Yes, due to APK integration.
Architecture decisions on whether gpkg should be modified to suit (“apkg” perhaps) or whether it is just dropped in favour of native APK, or APK should be patched to extend capabilities for Gargoyle.

Beyond that it’s not too bad.

[ispyisail]

That's how I was reading it as well.

What's your preference?

Do you want me to try drafting an AI conversion tool?

As projects get bigger, AI becomes less reliable, but with the right tools and techniques, larger tasks are now becoming possible.

You direct, we build.

[Lantis]

I am not really that interested in taking it on sorry.
I don't have the bandwidth to review the change.

If I had to choose one, extend APK to suit Gargoyle.

[ispyisail]

Is this the end of Gargoyle

[Lantis]

If you want to let Claude have a go at it you can try.

Prompt needs to be refined to keep it on track. My suggestion for context/promot:
- gpkg is a Gargoyle specific fork of opkg
- gpkg extended some features and customised returned data formats and attributes (e.g. JS format) to suit Gargoyle
- gpkg supported a “link-destination” command to symlink from a plugin root back to regular root (allowing simplified plugin installation on a usb drive)
- analyse gpkg capabilities, how these differ from opkg, and the equivalents for apk
- propose a set of patches for apk to create equivalent functionality where required
- if a set of patches becomes too complicated, copy apk source and modify/ship from Gargoyles repo. Let me decide on this but provide recommendations
- propose integration of apk to the rest of the gargoyle ecosystem (i.e. examine all gpkg calls and helper scripts and integrate replacements)
- propose any changes to the final stages of build.sh required to gather packages that may differ from the existing method.


But I will be slow to review this, AI might be writing code but my wrinkly brain has to review it the old fashioned way.

[ispyisail]

Ohh...

I've kind of given up on the idea of doing this as a collaboration.

Don't get me wrong—I still need a director. AI can make suggestions, but there's no substitute for your big-picture knowledge and experience.

What I've been doing over the last week is building an automated build machine. I've added pre-build tests (and I'm constantly adding more), an automated compiler, and an automated three-router VM with OpenVPN and WireGuard links. It's becoming a massive, fully automated system that's now getting to the point where it's running 24/7.

Every time I find a problem, I add another test and automate the fix so it doesn't happen again.

So far I've updated OpenVPN, WireGuard, and Tor.

At this point, I'm just going for it.

[ispyisail]

I will 100% get back to your recommendations

Just im the middle of some builds at the moment

[ispyisail]

My other suggestion is you could fight fire with fire

If you got Claude you could build custom verification tools

You tell Claude i want to create to test tools to verify PR based on rules i set. Then it just a simple click of the button to check PR

Just a thought..

[ispyisail]

gpkg -> apk Migration Plan (Analysis & Recommendations)

Date: 2026-07-03
Status: Research/planning document only. No code has been written or changed as part of this document. Nothing here has been actioned against gargoyle-src, gargoyle-docker, or upstream apk-tools. Every finding below is grounded in the actual source tree (package/gpkg/, package/gargoyle*/, build.sh) plus current (July 2026) web research on OpenWrt's apk transition — file:line references are given throughout so each claim can be checked independently.

___________________________________________________

0. TL;DR for a first pass

• Correction to the working premise: gpkg is not a patched fork of opkg's source code. It's an independent ~4,750-line C implementation written by Eric Bishop, sharing no code with opkg. It matches opkg at the level of on-disk formats and CLI shape only ("opkg compatible" per its own Makefile title). This matters because there is no such thing as "porting gpkg's diffs into apk" — every equivalent feature in apk would be freshly authored new code, not a transplant.
• gpkg is small in command surface but has two genuinely custom mechanisms worth caring about: (1) a multi-destination install model with a --link-dest flag for the USB-plugin-root use case, and (2) a -o js output mode that lets haserl backends embed package data straight into <script> blocks as JS literals, plus a curated set of Gargoyle-only computed attributes (Will-Fit, Required-Size, Install-Destination, etc.).
• gpkg is currently /bin/opkg on Gargoyle — literally symlinked over it at first boot (package/gpkg/files/gpkg-uci-defaults:30-32). Any migration has to reckon with the fact that gpkg isn't just "the package manager Gargoyle happens to use", it is the system's opkg, consuming the same /etc/opkg.conf.
• The call-site footprint is real but shallow: 9 files call gpkg directly, and of those, 7 use it for a one-line "is this package installed?" or "give me info as JS" check. Only 2 files (install_gargoyle_package.sh, remove_gargoyle_package.sh) touch the multi-destination/link-dest machinery specifically.
• External timing constraint, newly confirmed this session: OpenWrt itself only ships apk as the default package manager starting with 25.12 (released ~March 2026); the branch Gargoyle currently builds against, 24.10, still uses opkg, and its security support ends September 2026. This makes an OpenWrt branch bump a hard prerequisite — or, if apk is wanted sooner, apk-tools would need to be vendored/backported onto 24.10 by hand, which is extra work beyond just replacing gpkg. See §5 for the tradeoff.
• A separate external write-up you shared (folded in at §5a) largely corroborates this document independently on three of its four points (GUI rewrite scope, .ipk → .apk + signing, build-script breakage) — but its claim that current Gargoyle betas are anchored to OpenWrt 23.05 doesn't match this repo: build.sh:29-31 pins openwrt-24.10 right now, and its git history shows sustained 24.10 tracking, not a recent move off 23.05. Worth confirming which Gargoyle lineage that write-up was actually describing before treating its version numbers as current.
• The core architecture decision this document exists to inform: given the apk transition is coming (§5), what happens to gpkg? Three real options — (A) adapt gpkg into a thin layer over apk ("apkg"), keeping every existing call site unchanged; (B) drop gpkg, rewrite all call sites against native apk directly; (C) patch apk's own source to gain the missing capabilities. Recommendation (final call is yours): Option A. It's the only path where §7's call-site migration cost is close to zero, and it avoids Option C's risk of an ongoing rebase burden against a faster-moving upstream. Full reasoning and the specific conditions for reconsidering it are in §6.

___________________________________________________

1. What gpkg actually is (correcting the "fork of opkg" framing)

package/gpkg/Makefile:11-31 shows a from-scratch local build with no PKG_SOURCE/PKG_SOURCE_URL/PKG_HASH pointing at any opkg tarball — the C source lives entirely in package/gpkg/src/ and is authored by Eric Bishop (copyright headers, 2009). The package's own TITLE in that Makefile is:

Code: Select all

TITLE:= Gargoyle Package Manager (opkg compatible)

"opkg compatible" describes the contract, not the lineage:

• Same .ipk package file format, same Packages/Packages.gz feed index format, same /etc/opkg.conf config file syntax (dest, src/gz, etc.), same general status-database concept.
• Independent C implementation of all of it — package/gpkg/src/ totals 4,751 lines across 11 files:

Code: Select all

File           | Lines | Role (inferred from name + partial read)
-------------------------------------------------------------------------------------------------
load.c         | 1,588 | Core: Packages index parsing, status DB, conf/dest parsing
install.c      | 1,030 | Install transaction: dep resolution, multi-dest placement, link-dest...
remove.c       |   494 | Removal + --autoremove-same-dest
info.c         |   408 | Attribute computation + -o js / output formatting
gpkg.c         |   368 | CLI entry point, subcommand dispatch, getopt_long table
alternatives.c |   175 | update-alternatives-style symlink management
gpkg.h         |   183 | Shared header
upgrade.c      |   160 | gpkg upgrade
conf.c         |   128 | /etc/opkg.conf-equivalent parsing
list.c         |    90 | list / list-installed
update.c       |    57 | Feed-list refresh
xsystem.c      |    70 | Subprocess exec helper

(install.c, remove.c, info.c, gpkg.c were read in enough detail to ground the CLI/attribute claims below; the rest were sized but not read line-by-line — a deeper read of load.c and install.c specifically would be worthwhile before any patch work begins, since that's where --link-dest's actual symlink logic and the status-DB format live.)

• Depends on Gargoyle's own helper libs (+libericstools +libbbtargz +ewget, package/gpkg/Makefile:33) — i.e. gpkg has its own internal dependencies on other Gargoyle-authored C code, which is extra surface area if any part of gpkg needed to be preserved as-is alongside apk during a transition.

The binary-replacement detail — package/gpkg/files/gpkg-uci-defaults:30-32:

Code: Select all

if [ ! -e /bin/opkg ] ; then
    ln -s /usr/bin/gpkg /bin/opkg
fi

gpkg doesn't sit next to opkg — on a Gargoyle install, /bin/opkg is gpkg. The same first-boot script also seeds /etc/opkg.conf from a template (/etc/opkg.gpkg.tmp) and keeps the plugin_root dest line and the OpenWrt/Gargoyle feed URLs in sync across firmware upgrades (lines 5-28). Anything that assumes "just call opkg" on a Gargoyle box is already calling gpkg today.

___________________________________________________

2. gpkg's custom data formats and attributes

2.1 Output format flag: --output-format / -o
From gpkg.c's option table, -o / --output-format accepts at least a js mode. In practice every caller in the tree uses -o 'js'. Confirmed usage, e.g. package/gargoyle/files/www/plugins.sh:30-31:

Code: Select all

pkg_info=$(gpkg info -v 'Install-Destination,Required-Size,Required-Depends,Description,Will-Fit,User-Installed' -d plugin_root -o 'js' -r '/^plugin\-gargoyle/')
gpkg dest-info -o 'js'

-o js makes gpkg itself emit ready-to-eval JavaScript (arrays/object literals), not JSON. The haserl backend just echoes gpkg's stdout straight into a <script> block; there is no separate JSON-decode step anywhere in the JS frontend. Confirmed by grepping plugins.js for gpkg — zero hits. All gpkg invocation lives in backend .sh files; the frontend only ever consumes the JS globals the backend already built for it.

2.2 Custom/computed attributes (-v / --package-variables)
Grepping info.c for the attribute-name string literals it recognizes gives the full set gpkg can emit via -v:

Code: Select all

All-Depends
Alternatives
Install-Destination
Required-Depends
Required-Size
Version
Will-Fit

Plus standard Packages-file-derived fields like Status/Description that get passed straight through. The Gargoyle-specific ones — Install-Destination, Required-Size, Required-Depends, Will-Fit, User-Installed, Alternatives — imply gpkg does real work opkg's own info subcommand doesn't do:

• Will-Fit: computes available space on the target dest versus the package's installed size before install is attempted.
• Install-Destination: which named dest a package is (or would be) installed to.
• Required-Size / Required-Depends: transitive size/dependency accounting across the whole dependency chain, not just the one package.

2.3 Regex filtering (-r / --matching-regex)
Used pervasively for cheap "is package X installed?" checks without the caller needing to grep gpkg's raw output themselves, e.g. quotas.sh:24:

Code: Select all

echo "var tcInstalled=\""$(gpkg list-installed -r "^tc-(tiny|full)" 2>&1)"\";"

___________________________________________________

3. The link-destination / USB-plugin-root feature

This is gpkg's most architecturally distinctive feature and the one your brief specifically called out. Full mechanism, read end-to-end from package/gargoyle/files/usr/lib/gargoyle/install_gargoyle_package.sh:

Code: Select all

plugin_root="/plugin_root"
...
have_plugin_root=$(cat /etc/opkg.conf | grep "dest.*$escaped_plugin_root")
if [ -z "$have_plugin_root" ] ; then
    echo "dest plugin_root $plugin_root" >>/etc/opkg.conf
fi
if [ ! -e "$plugin_root" ] ; then
    mkdir -p "$plugin_root"
fi
link_dirs="etc tmp var"
for link_dir in $link_dirs ; do
    if [ ! -h "$plugin_root/$link_dir" ] ; then
        rm -rf "$plugin_root/$link_dir"
        ln -s "/$link_dir" "$plugin_root/$link_dir"
    fi
done

gpkg update
gpkg install --force-overwrite --dest plugin_root --link-dest root "$pkg"

Two layers, worth keeping conceptually separate because only one of them is gpkg-specific:

1. dest plugin_root /plugin_root in /etc/opkg.conf — this is a stock opkg feature, not a gpkg extension.
2. --link-dest root on top of --dest plugin_root — this is the gpkg-specific extension. It tells gpkg, while installing onto the plugin_root destination, to also treat the root destination as a link target for whatever gpkg's install logic decides needs linking back.

Removal is symmetric and simpler — package/gargoyle/files/usr/lib/gargoyle/remove_gargoyle_package.sh:12:

Code: Select all

gpkg remove --autoremove-same-dest "$pkg"

___________________________________________________

4. Full capability comparison — gpkg vs. opkg vs. apk

Code: Select all

Capability                                | opkg (stock) | gpkg                  | apk (Alpine/OpenWrt)
-------------------------------------------------------------------------------------------------------------------------------------
.ipk install from feeds                   | Yes          | Yes                   | No (uses .apk and APKINDEX.tar.gz)
Multiple named install dests in config    | Yes (native) | Yes (inherited)       | Not natively (uses single --root <path>)
Cross-dest linking (--link-dest)          | No           | Yes (gpkg-only)       | No (needs new code)
Space-fit precheck (Will-Fit)             | No           | Yes (gpkg-only)       | No
JS-literal output mode (-o js)            | No           | Yes (gpkg-only)       | No (structured JSON upstream, but no JS-literal)
Regex package-name filtering (-r)         | Partial      | Built-in (gpkg-only)  | Not built-in the same way
--autoremove-same-dest                    | No           | Yes (gpkg-only)       | Has autoremove concepts but not dest-scoped
Local .ipk file install                   | Yes          | Yes                   | Yes (for .apk files)
Actively maintained upstream              | No           | N/A (Gargoyle)        | Yes
Default in current OpenWrt target (24.10) | Yes          | (replaces it)         | No (24.10 ships opkg)
Default in OpenWrt stable (25.12)         | No           | N/A                   | Yes

The honest summary: apk is a strict downgrade in gpkg-specific capability out of the box, because apk was never designed around Gargoyle's plugin-root/USB use case.

___________________________________________________

5. External constraint: OpenWrt's actual opkg → apk timeline

Verified via web search (July 2026):

• OpenWrt 25.12.0 (released ~March 2026) is the first release where apk replaces opkg as the default package manager. (linuxiac.com, helpnetsecurity.com)
• OpenWrt 24.10 — the branch Gargoyle currently builds against — still uses opkg. Security support for 24.10 ends September 2026.
• OpenWrt 23.05 also still uses opkg.
• OpenWrt's own opkg fork is no longer maintained upstream.
• OpenWrt publishes an official opkg → apk cheat sheet for CLI-syntax differences. (forum.openwrt.org)

Implication: To get apk "for free", Gargoyle's build needs to track OpenWrt 25.12+ rather than 24.10.

___________________________________________________

5a. Cross-checking an external summary of this problem

1. "The Plugin GUI requires a complete rewrite" — largely confirmed. Matches §7's call-site inventory: plugins.sh is the highest-effort file.
2. ".ipk → .apk repackaging, with strict signatures" — confirmed. apk enforces signature verification where opkg does not. Without a resolved signing setup, every Gargoyle-built plugin fails to install by default.
3. "Custom build environment breakage" — confirmed. Matches what §8 documents concretely: build.sh's globbing logic.
4. "The Version Anchor — Gargoyle 1.15.x is built on OpenWrt 23.05" — does not match this repository. build.sh:29-31 pins branch_name="24.10" right now.

___________________________________________________

6. The actual architecture decision: three paths

Given that an OpenWrt branch bump to 25.12 forces the opkg → apk swap sooner or later, what happens to gpkg?

Code: Select all

Metric                            | A. Adapt gpkg → "apkg"          | B. Drop gpkg, use native apk    | C. Patch apk's source
-----------------------------------------------------------------------------------------------------------------------------------
§7 call-site rewrites needed      | None                            | All 9 files                     | All 9 files 
Who maintains what afterward      | Gargoyle owns a thin wrapper    | Gargoyle owns shell helpers     | Gargoyle owns patch series
Risk of breaking on upstream bump | Low                             | Low                             | High (re-verify every bump)
Where multi-dest logic lives      | Inside gpkg/apkg C code         | New shell wrappers              | Inside apk's internals
Depends on upstream agreement     | No                              | No                              | Yes
Fits "not too bad" framing        | Best fit                        | Partial fit                     | Worst fit

Recommendation: Option A ("apkg").
It's the only option where the §7 integration cost is close to zero, it avoids Option C's upstream-churn risk entirely, and it's the most direct continuation of what gpkg already is today.

___________________________________________________

7. Integration plan: full gpkg call-site inventory

Code: Select all

File                                                  | Replacement Complexity | Reason
--------------------------------------------------------------------------------------------------------------------------
gargoyle/install_gargoyle_package.sh                  | High                   | Needs full multi-dest + link-dest feature
gargoyle/remove_gargoyle_package.sh                   | Medium                 | Needs dest-scoped autoremove only
gargoyle/www/plugins.sh                               | High                   | Needs JS output, computed attributes, etc.
gargoyle/www/quotas.sh                                | Low                    | Simple installed-check with regex
gargoyle/www/port_forwarding.sh                       | Low                    | Simple installed-check, exact name
gargoyle-i18n/www/languages.sh                        | Medium                 | Needs JS output + dest-awareness
gargoyle-i18n/www/firstboot.i18n.sh                   | Medium                 | Same as languages.sh, first-boot context
gargoyle-i18n/usr/lib/gargoyle/i18nServices.sh        | Low                    | Plain local-file install
gargoyle-i18n/www/js/i18n.js                          | None                   | Frontend consumes backend globals
plugin-gargoyle-tor/www/tor.sh                        | Medium                 | Needs dest-info subcommand + JS output
gargoyle/Makefile                                     | Trivial                | Swap dependency line
gpkg/Makefile, src/*.c, files/gpkg-uci-defaults       | N/A                    | This is what is being replaced

___________________________________________________

8. Proposed changes to build.sh's final package-gathering stage

1. File extension: Every find ... -name "*.ipk" needs an .apk variant.
2. Index format: find ... -name "Packa*" matches opkg's indexes. apk's index is APKINDEX.tar.gz. The glob pattern needs to change.
3. Signing: apk's index format is cryptographically signed by design. An apk-based build will need a signing-key story.
4. distrib_copy_arch_ind_ipk naming: Rename the function alongside the extension change to avoid stale-name confusion.

___________________________________________________

9. Suggested order of operations

1. Confirm the §7 open question: settle whether a persistent multi-root/multi-dest config exists or needs to be added in apk.
2. Prototype the Low/Trivial call sites first (quotas.sh, port_forwarding.sh, i18nServices.sh).
3. Build the shared JS-output wrapper once, use it for all four JS-output call sites.
4. Prototype install_gargoyle_package.sh's link-dest case against Option A (apkg) first.
5. Only after 1-4 are validated, tackle build.sh's final-stage gathering changes (§8) and the signing-key process question.
6. Decide, with real prototype evidence in hand, whether Option A holds up as recommended.

[/code]