Knowledge Base updated: 2026-11-16
Knowledge Base Index
Orientation
This repository builds and documents WSABuilds: customized Windows Subsystem for Android packages with optional Magisk, KernelSU, GApps, Amazon Appstore, and bundled runtime payloads. The highest-level flow is GitHub Actions invoking the MagiskOnWSA build pipeline to discover upstream downloads, extract and patch payloads, package an installable Windows app, and publish/support user-facing builds.
Main parts:
.github/— CI/release automation for active, legacy, tester, and update workflows.MagiskOnWSA/— active build scripts, installer resources, runtime hooks, XML request templates, and bundled payloads.MagiskOnWSAOld/— legacy build pipeline and old-build payload tree.WSABuilds Utilities/— standalone updater and uninstaller utilities for installed builds.Documentation/,MagiskOnWSA/docs/, and root docs — user install, usage, troubleshooting, and custom-build guidance.
Critical state is mostly file-based rather than service-backed: workflow state lives in GitHub Actions artifacts/releases, generated build state is produced in the build workspace, installer/runtime payloads live under MagiskOnWSA/** and MagiskOnWSAOld/**, and user guidance lives in Markdown documentation trees.
Architecture diagrams
flowchart TD
subgraph Automation[.github]
Workflows[GitHub Actions workflows]
Dependabot[dependabot.yml]
end
subgraph Active[MagiskOnWSA]
Build[build/run/install deps]
Discovery[download discovery scripts + xml]
Extract[extract + patch helpers]
Installer[installer resources]
Runtime[root/runtime assets]
Payloads[bundled binaries]
end
subgraph Legacy[MagiskOnWSAOld]
OldScripts[legacy scripts]
OldPayloads[legacy payloads + installer]
end
subgraph Support[Support surfaces]
Utilities[WSABuilds Utilities]
Docs[user-facing docs]
end
Upstreams[Microsoft Store / Magisk / KernelSU / GApps sources]
Releases[GitHub releases/artifacts]
Users[Windows users]
Workflows --> Build
Workflows --> OldScripts
Build --> Discovery
Discovery --> Upstreams
Build --> Extract
Extract --> Payloads
Extract --> Runtime
Build --> Installer
OldScripts --> OldPayloads
Installer --> Releases
OldPayloads --> Releases
Releases --> Users
Utilities --> Users
Docs --> Users
Dependabot --> Workflows
flowchart LR
Workflow[build workflow] --> BuildSh[MagiskOnWSA/scripts/build.sh]
BuildSh --> LinkScripts[generate*Link.py + WSAUpdateChecker.py]
LinkScripts --> XML[MagiskOnWSA/xml request templates]
LinkScripts --> Downloads[upstream package URLs]
BuildSh --> Extractors[extractWSA.py / extractMagisk.py]
Extractors --> Patch[fixGappsProp.py + DLL assets]
Patch --> RuntimeAssets[root hooks, certs, sepolicy]
RuntimeAssets --> Installer[installer package resources]
Installer --> Output[installable WSABuilds package]
flowchart TD
User[Installed WSABuilds user] --> UpdateUtility[WSABuilds Utilities/Update Script]
User --> UninstallUtility[WSABuilds Utilities/Uninstall Script]
UpdateUtility --> InstalledPackage[local WSA install]
UpdateUtility --> ReleaseAssets[available build assets]
UninstallUtility --> InstalledPackage
User --> Guides[Documentation usage/fix guides]
Glossary
- WSABuilds — this repository's customized Windows Subsystem for Android distributions and supporting utilities.
- MagiskOnWSA — the active build tree for creating rooted/customized WSA packages.
- MagiskOnWSAOld — retained legacy build tree for old WSABuilds variants.
- WSA — Windows Subsystem for Android, the upstream package being downloaded, patched, and repackaged.
- AMZ — shorthand in docs and options for the Amazon Appstore component.
Codebase-wide invariants
- Active build logic is separated from legacy build logic: active scripts and payloads live under
MagiskOnWSA/**, while legacy equivalents live underMagiskOnWSAOld/**. - GitHub automation is centralized under
.github/**, with workflow entrypoints in .github/…/*.yml. - User-facing Markdown is split between broad WSABuilds documentation under
Documentation/**and active MagiskOnWSA project docs underMagiskOnWSA/docs/**. - Standalone end-user utilities are kept outside the build trees under
WSABuilds Utilities/Update Script/**andWSABuilds Utilities/Uninstall Script/**.
Routing table
.github/**-> docs/github-automation.md- MagiskOnWSA/…/build.sh -> docs/magiskonwsa-build-orchestrator.md
- MagiskOnWSA/…/run.sh -> docs/magiskonwsa-build-orchestrator.md
- MagiskOnWSA/…/install_deps.sh -> docs/magiskonwsa-build-orchestrator.md
- MagiskOnWSA/…/requirements.txt -> docs/magiskonwsa-build-orchestrator.md
- MagiskOnWSA/…/generateWSALinks.py -> docs/magiskonwsa-download-discovery.md
- MagiskOnWSA/…/generateMagiskLink.py -> docs/magiskonwsa-download-discovery.md
- MagiskOnWSA/…/generateKernelSULink.py -> docs/magiskonwsa-download-discovery.md
- MagiskOnWSA/…/generateGappsLink.py -> docs/magiskonwsa-download-discovery.md
- MagiskOnWSA/…/WSAUpdateChecker.py -> docs/magiskonwsa-download-discovery.md
MagiskOnWSA/xml/**-> docs/magiskonwsa-download-discovery.md- MagiskOnWSA/…/priconfig.xml -> docs/magiskonwsa-installer-packaging.md
- MagiskOnWSA/…/extractWSA.py -> docs/magiskonwsa-extraction-patching.md
- MagiskOnWSA/…/extractMagisk.py -> docs/magiskonwsa-extraction-patching.md
- MagiskOnWSA/…/fixGappsProp.py -> docs/magiskonwsa-extraction-patching.md
MagiskOnWSA/DLL/**-> docs/magiskonwsa-extraction-patching.mdMagiskOnWSA/installer/**-> docs/magiskonwsa-installer-packaging.mdMagiskOnWSA/arm64/**-> docs/magiskonwsa-installer-packaging.mdMagiskOnWSA/scripts/init.lsp.magisk.rc-> docs/magiskonwsa-android-root-runtime.md- MagiskOnWSA/…/post-fs-data.sh -> docs/magiskonwsa-android-root-runtime.md
- MagiskOnWSA/…/magisk_debug.sh -> docs/magiskonwsa-android-root-runtime.md
MagiskOnWSA/scripts/sepolicy.rule-> docs/magiskonwsa-android-root-runtime.mdMagiskOnWSA/cacerts/**-> docs/magiskonwsa-android-root-runtime.mdMagiskOnWSA/bin/**-> docs/magiskonwsa-bundled-payloads.mdMagiskOnWSA/libhoudini/**-> docs/magiskonwsa-bundled-payloads.mdMagiskOnWSA/*.gitattributes-> docs/magiskonwsa-bundled-payloads.mdMagiskOnWSA/.gitignore-> docs/magiskonwsa-bundled-payloads.mdMagiskOnWSA/LICENSE-> docs/magiskonwsa-bundled-payloads.mdMagiskOnWSAOld/scripts/**-> docs/magiskonwsaold-build-pipeline.mdMagiskOnWSAOld/installer/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/arm64/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/x64/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/bin/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/cacerts/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/DLL/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/libhoudini/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/linker/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/xml/**-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/.gitattributes-> docs/magiskonwsaold-payloads-and-installer.mdMagiskOnWSAOld/LICENSE-> docs/magiskonwsaold-payloads-and-installer.mdWSABuilds Utilities/**-> docs/wsabuilds-desktop-utilities.md- README.md -> docs/user-facing-documentation.md
LICENSE-> docs/user-facing-documentation.mdLICENSE-CC-BY-NC-ND-> docs/user-facing-documentation.mdDocumentation/**-> docs/user-facing-documentation.mdMagiskOnWSA/docs/**-> docs/user-facing-documentation.md- any change to active build orchestration, build options, or packaging phase order -> docs/magiskonwsa-build-orchestrator.md
- any change to upstream WSA/Magisk/KernelSU/GApps discovery behavior -> docs/magiskonwsa-download-discovery.md
- any change to Android boot/root integration assets -> docs/magiskonwsa-android-root-runtime.md
- any change to old-build support or legacy payload compatibility -> docs/magiskonwsaold-build-pipeline.md and docs/magiskonwsaold-payloads-and-installer.md