Introducing a new way to review your PRs.

Read the announcement

mustardchef / wsabuilds

Run Windows Subsystem For Android on your Windows 10 and Windows 11 PC using prebuilt binaries with Google Play Store (MindTheGapps) and/or Magisk or KernelSU (root solutions) built in.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / magiskonwsa-build-orchestrator

MagiskOnWSA build orchestrator

Overview

The active build orchestration layer is centered on MagiskOnWSA/…/build.sh. It must be executed by Bash on an x86_64 or aarch64 host, changes into MagiskOnWSA/scripts, creates a temporary work directory, and uses ../download as the cache for WSA, dependency AppX packages, Magisk/KernelSU, GApps, and the Magisk custom image. It writes its final unpacked package directory under ../output and appends GitHub Actions-style metadata (artifact_folder, artifact, arch, built, file_ext) to $GITHUB_OUTPUT.

MagiskOnWSA/…/run.sh is the interactive wrapper. It first runs ./install_deps.sh, then uses whiptail or dialog to collect build choices and translates them into build.sh command-line options. The wrapper covers architecture, WSA release channel, optional root, root solution, Magisk channel, optional GApps, optional Amazon Appstore removal, and optional compression format. It then executes ./build.sh "${COMMAND_LINE[@]}".

MagiskOnWSA/…/install_deps.sh prepares the host before either interactive or direct builds. It checks for whiptail or dialog, pip, aria2c, 7z, and unzip; identifies a Linux package manager from release marker files; runs package-manager update/upgrade commands with sudo; installs missing packages using distro-specific package names; and installs Python requirements from MagiskOnWSA/…/requirements.txt. For Python 3.11+ or when a virtual environment already exists, it creates or refreshes MagiskOnWSA/python3-env with --system-site-packages, activates it while validating/installing requirements, then deactivates it. Otherwise it installs the Python requirements into the current Python environment. The Python dependency declaration is intentionally small: requests for network/API calls and packaging for version comparison.

build.sh accepts --arch x64|arm64, --release-type retail|RP|WIS|WIF, --magisk-ver stable|beta|canary|debug|release, --root-sol magisk|kernelsu|none, --compress-format 7z|zip|none, plus --offline, --magisk-custom, --install-gapps, --remove-amazon, --skip-download-wsa, --debug, and --help. Defaults are x64, retail, stable, magisk, and none compression. If GApps is requested with --root-sol none, build.sh forces Magisk because GApps is mounted through Magisk; if GApps is requested with KernelSU, it aborts.

The main build phases in build.sh are:

  1. Initialize cleanup and state. build.sh creates a mktemp work directory and a work environment file at $WORK_DIR/ENV, exporting it as WSA_WORK_ENV. Helper Python scripts update this file with values such as WSA_VER, WSA_MAJOR_VER, WSA_REL, MAGISK_VERSION_NAME, MAGISK_VERSION_CODE, and KERNELSU_VER; build.sh re-sources it after extraction/link-generation phases. Exit traps remove the work directory, optional $TMPDIR, and any transient ../download/download.list; failure paths may also remove partially downloaded artifacts.
  2. Generate and download WSA inputs. Unless --offline is set, build.sh calls generateWSALinks.py to write aria2 entries for the selected architecture/release into ../download/download.list, then runs aria2c against that list. With --skip-download-wsa, it still asks generateWSALinks.py for dependency AppX links while omitting the WSA bundle itself.
  3. Extract WSA. build.sh requires ../download/wsa-$RELEASE_TYPE.zip, calls extractWSA.py, and sources $WSA_WORK_ENV. extractWSA.py expands the architecture-specific WSA package into $WORK_DIR/wsa/$ARCH, extracts language/scale resource PRI/XML/image files, and records the WSA version/release values that later drive artifact naming. Builds older than WSA major version 2211 switch the GApps Android API selector from 33 to 32.
  4. Generate and download optional artifacts. Unless offline, build.sh asks generateMagiskLink.py for Magisk and cust.img when Magisk root is selected and not custom; asks generateKernelSULink.py for a KernelSU ZIP matched to the WSA kernel version when KernelSU is selected; and asks generateGappsLink.py for the GApps image and rc file when GApps is selected. All generated links are appended to the same aria2 download list and fetched into ../download.
  5. Validate cached inputs. Offline and online flows converge on a file-existence check for required AppX dependencies (Microsoft.VCLibs.140.00_$ARCH.appx, Microsoft.VCLibs.140.00.UWPDesktop_$ARCH.appx, and Microsoft.UI.Xaml.2.8_$ARCH.appx), plus root/GApps-specific files. Custom Magisk is expected as ../download/magisk-$MAGISK_VER.zip, with fallback to ../download/app-$MAGISK_VER.apk.
  6. Integrate root and GApps. For Magisk, build.sh calls extractMagisk.py, verifies non-stable downloaded Magisk builds are 26.0+, compresses Magisk payloads with extracted magiskboot, and patches $WORK_DIR/wsa/$ARCH/Tools/initrd.img to replace /init with ../bin/$ARCH/lspinit, add Magisk init binaries, add init.lsp.magisk.rc, post-fs-data.sh, and embed cust.img. For KernelSU, it sources the generated .info file, unzips the KernelSU package, normalizes the kernel filename (bzImage on x64, Image on arm64), and replaces $WORK_DIR/wsa/$ARCH/Tools/kernel. For GApps, it uses Magisk's magiskboot to add gapps.rc and lsp_gapps.img into the initrd overlay.
  7. Finalize package contents and output. If requested, Amazon Appstore apex files matching mado*.apex are removed. build.sh deletes AppX signature/block-map metadata, copies VCLibs/Xaml packages, ../bin/$ARCH/makepri.exe, ../…/priconfig.xml, and installer files from ../installer into the WSA package, writes a top-level filelist.txt, constructs a descriptive artifact name, and moves $WORK_DIR/wsa/$ARCH to ../output/WSA_${WSA_VER}_${ARCH}.

Covered-file roles:

Coupling

  • If MagiskOnWSA/…/build.sh option names or allowed values change, update MagiskOnWSA/…/run.sh at the same time. run.sh builds a positional COMMAND_LINE array and maps release labels to retail, RP, WIS, and WIF; mismatches surface only when the final build.sh parse/validation rejects the wrapper's generated arguments.
  • If helper scripts change the variables they write into $WSA_WORK_ENV, verify the corresponding source "$WSA_WORK_ENV" consumers in MagiskOnWSA/…/build.sh. extractWSA.py, extractMagisk.py, and generateKernelSULink.py communicate WSA, Magisk, and KernelSU versions through that shell-readable file rather than a typed interface.
  • If artifact filenames or cache locations change in MagiskOnWSA/…/build.sh, also update the Python link generators and offline-file checks that must produce or validate the same names. Examples include wsa-$RELEASE_TYPE.zip, magisk-$MAGISK_VER.zip, cust.img, kernelsu-$ARCH-$KERNEL_VER.zip, and gapps-${ANDROID_API_MAP[$ANDROID_API]}-${ARCH_NAME_MAP[$ARCH]}.img.
  • If MagiskOnWSA/…/requirements.txt changes, verify both branches in MagiskOnWSA/…/install_deps.sh: the venv branch checks requirements through pkg_resources.require(open('requirements.txt', mode='r')), while the non-venv branch installs with python3 -m pip install -r requirements.txt -q.

Risks

  • MagiskOnWSA/…/build.sh writes to $GITHUB_OUTPUT unconditionally near the end. Outside GitHub Actions, an unset GITHUB_OUTPUT can cause the completed local build to fail at metadata emission even after the package was moved into ../output.
  • MagiskOnWSA/…/install_deps.sh runs package-manager update/upgrade steps before installing missing tools, and for pacman/emerge requires the user to accept a full system upgrade. Running MagiskOnWSA/…/run.sh always invokes this dependency script first, so interactive builds can be blocked or make broad host changes before any build options are selected.
  • MagiskOnWSA/…/build.sh removes $TMPDIR during cleanup if $TMPDIR was set and existed. If the caller points TMPDIR at a shared or non-build-specific directory, abort or normal exit cleanup can delete unrelated temporary contents.