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:
- Initialize cleanup and state. build.sh creates a
mktempwork directory and a work environment file at$WORK_DIR/ENV, exporting it asWSA_WORK_ENV. Helper Python scripts update this file with values such asWSA_VER,WSA_MAJOR_VER,WSA_REL,MAGISK_VERSION_NAME,MAGISK_VERSION_CODE, andKERNELSU_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. - Generate and download WSA inputs. Unless
--offlineis set, build.sh calls generateWSALinks.py to write aria2 entries for the selected architecture/release into../download/download.list, then runsaria2cagainst that list. With--skip-download-wsa, it still asks generateWSALinks.py for dependency AppX links while omitting the WSA bundle itself. - 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 version2211switch the GApps Android API selector from 33 to 32. - Generate and download optional artifacts. Unless offline, build.sh asks generateMagiskLink.py for Magisk and
cust.imgwhen 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. - 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, andMicrosoft.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. - 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.imgto replace/initwith../bin/$ARCH/lspinit, add Magisk init binaries, addinit.lsp.magisk.rc, post-fs-data.sh, and embedcust.img. For KernelSU, it sources the generated.infofile, unzips the KernelSU package, normalizes the kernel filename (bzImageon x64,Imageon arm64), and replaces$WORK_DIR/wsa/$ARCH/Tools/kernel. For GApps, it uses Magisk'smagiskbootto addgapps.rcandlsp_gapps.imginto the initrd overlay. - Finalize package contents and output. If requested, Amazon Appstore apex files matching
mado*.apexare removed. build.sh deletes AppX signature/block-map metadata, copies VCLibs/Xaml packages,../bin/$ARCH/makepri.exe, ../…/priconfig.xml, and installer files from../installerinto the WSA package, writes a top-level filelist.txt, constructs a descriptive artifact name, and moves$WORK_DIR/wsa/$ARCHto../output/WSA_${WSA_VER}_${ARCH}.
Covered-file roles:
- MagiskOnWSA/…/build.sh: non-interactive build entrypoint and phase orchestrator; validates options, coordinates downloads/extraction/root integration/final packaging, and writes output metadata.
- MagiskOnWSA/…/run.sh: interactive terminal UI wrapper that installs dependencies, collects user choices, and forwards them as build.sh options.
- MagiskOnWSA/…/install_deps.sh: host dependency bootstrapper for system packages, Python virtual environment creation, and Python package installation.
- MagiskOnWSA/…/requirements.txt: Python dependency list consumed by install_deps.sh; currently
requestsandpackaging, matching the helper scripts invoked by build.sh.
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_LINEarray and maps release labels toretail,RP,WIS, andWIF; 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 correspondingsource "$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, andgapps-${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 withpython3 -m pip install -r requirements.txt -q.
Risks
- MagiskOnWSA/…/build.sh writes to
$GITHUB_OUTPUTunconditionally near the end. Outside GitHub Actions, an unsetGITHUB_OUTPUTcan 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/emergerequires 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
$TMPDIRduring cleanup if$TMPDIRwas set and existed. If the caller pointsTMPDIRat a shared or non-build-specific directory, abort or normal exit cleanup can delete unrelated temporary contents.