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-extraction-patching

MagiskOnWSA Extraction and Payload Patching

Overview

This stage turns previously discovered/downloaded WSA, Magisk, GApps, and patch assets into a mutable WSA package tree that later packaging scripts can sign, install, or archive. The active entrypoints are the Python helpers in MagiskOnWSA/scripts/ and their vendored/WSAPatch copy under MagiskOnWSA/DLL/scripts/, with the orchestration visible in MagiskOnWSA/…/build.sh.

Path responsibilities:

  • MagiskOnWSA/…/extractWSA.py and MagiskOnWSA/…/extractWSA.py unpack the upstream Microsoft WSA archive into <workdir>/wsa/<arch>/, extract language/scale resource packages into pri/, xml/, and Images/, and write WSA version metadata into the environment file used by the build.
  • MagiskOnWSA/…/extractMagisk.py and MagiskOnWSA/…/extractMagisk.py unpack architecture-specific Magisk native libraries from a Magisk APK/zip into <workdir>/magisk/, normalize library names to executable payload names, and record Magisk version metadata in WSA_WORK_ENV when available.
  • MagiskOnWSA/…/fixGappsProp.py and MagiskOnWSA/…/fixGappsProp.py rewrite mounted Android build.prop files so integrated GApps see Google-like product identity, fingerprints, descriptions, model, and device values.
  • MagiskOnWSA/DLL/bin/{x64,arm64}/lspinit, MagiskOnWSA/DLL/scripts/init.lsp.magisk.rc, MagiskOnWSA/…/post-fs-data.sh, and MagiskOnWSA/DLL/scripts/sepolicy.rule are the initrd patch payloads that make Magisk/GApps boot-time integration work.
  • MagiskOnWSA/…/priconfig.xml is copied into the extracted package before PRI regeneration; MagiskOnWSA/DLL/xml/{GetCookie.xml,WUIDRequest.xml,FE3FileUrl.xml} are SOAP templates consumed by the download-discovery side of the same DLL bundle, before this extraction stage.
  • MagiskOnWSA/DLL/WsaPatch.dll and MagiskOnWSA/DLL/icu.dll are Windows PE DLL assets from WSAPatch; MagiskOnWSA/…/README.md points to the upstream WSAPatch release source. The extraction helpers do not modify these binaries, but they travel with this payload bundle.
  • MagiskOnWSA/DLL/cacerts/** and MagiskOnWSA/DLL/docs/** are bundled certificate/help assets in the DLL tree rather than code paths used by the extraction helpers read here.

extractWSA.py consumes four positional arguments: target WSA architecture (x64 or arm64), the downloaded WSA zip path, a temporary root directory, and an environment-file path. It deletes any existing <rootdir>/wsa, creates <rootdir>/wsa/<arch>, then scans the outer WSA download archive. Any inner package whose filename contains the requested architecture is extracted to <rootdir>/wsa/ and then fully expanded into <rootdir>/wsa/<arch>/. The top-level script version additionally parses the architecture package filename into WSA_VER, WSA_MAJOR_VER, and WSA_REL; the DLL copy records WSA_VER and WSA_REL. For language and scale packages in the same outer archive, it extracts resources.pri as resources.<name>.pri under <arch>/pri/, AppxManifest.xml as resources.<name>.xml under <arch>/xml/, and matching Images/*.png files into the architecture package tree.

extractMagisk.py consumes the build architecture, a Magisk zip/APK path, and the temporary work directory. It reads Magisk version and versionCode from the zip comment, writes MAGISK_VERSION_NAME and MAGISK_VERSION_CODE into the file named by WSA_WORK_ENV when that environment variable exists, and extracts Magisk binaries under <workdir>/magisk/. The architecture map is WSA-oriented: x64 maps to Magisk APK ABIs x86_64 and x86, while arm64 maps to arm64-v8a and armeabi-v7a. The active top-level helper supports both current split names (libmagisk64.so/libmagisk32.so) and older single libmagisk.so packages, optionally extracts libinit-ld.so as init-ld, always extracts libmagiskinit.so as magiskinit, and extracts libmagiskboot.so for the host ABI so the build machine can run it. The DLL copy assumes the split libmagisk64.so and libmagisk32.so names.

The actual initrd patching shown in MagiskOnWSA/…/build.sh happens after extraction. For Magisk/GApps builds, magiskboot compresses the extracted Magisk payloads to .xz, then rewrites Tools/initrd.img to move the original /init to /wsainit, add the architecture-specific MagiskOnWSA/DLL/bin/<arch>/lspinit, symlink /init to /lspinit, add magiskinit, add overlay.d/init.lsp.magisk.rc, add overlay.d/…/post-fs-data.sh, and add lsp_cust.img from the downloaded custom image. When GApps are requested, the same initrd receives MagiskOnWSA/DLL/scripts/sepolicy.rule, a downloaded GApps rc file, and a downloaded GApps image as overlay.d/sbin/lsp_gapps.img.

At runtime, MagiskOnWSA/DLL/scripts/init.lsp.magisk.rc runs post-fs-data.sh during Android post-fs-data. post-fs-data.sh creates /data/adb and /data/adb/magisk if missing, extracts Magisk tools and scripts from the embedded Magisk stub APK according to ro.product.cpu.abi, then loop-mounts any temporary lsp_*.img payloads, runs each payload's own post-fs-data.sh, unmounts it, and deletes the image. MagiskOnWSA/DLL/scripts/sepolicy.rule grants GMSCore-specific socket/property/tmpfs access needed by GApps integration.

fixGappsProp.py is a filesystem mutator rather than an archive extractor. It consumes the root of an already extracted or mounted Android system tree plus a desired product name and model. It visits system/build.prop, vendor/build.prop, vendor/odm/etc/build.prop, and vendor/vendor_dlkm/etc/build.prop if present, appends a marker comment, sets Google brand/manufacturer/name/device/model/product/flavor properties, and recomputes global and section-specific ro.build.description, ro.build.fingerprint, ro.<sec>.build.description, ro.<sec>.build.fingerprint, and ro.bootimage.build.fingerprint values from the existing Android version/id/incremental/type/tag fields.

This stage fits between download discovery and final packaging: discovery scripts produce wsa-<release>.zip, magisk-<ver>.zip, GApps images/rc files, custom images, and dependency AppX files; the extraction/patching helpers create the patched <workdir>/wsa/<arch> tree and modified Tools/initrd.img; later packaging code removes Microsoft signatures, adds dependency AppX/install scripts, generates file lists, moves the result to output/WSA_<version>_<arch>_..., and optionally compresses it.

Coupling

Risks

  • MagiskOnWSA/…/extractWSA.py and MagiskOnWSA/…/extractWSA.py select the first archive member whose lowercase filename contains the architecture string. If Microsoft ships multiple matching packages in the outer WSA archive, the helper can extract the wrong inner package and later packaging will operate on an unexpected package tree.
  • MagiskOnWSA/…/extractMagisk.py lacks the fallback logic present in MagiskOnWSA/…/extractMagisk.py for Magisk zips that expose only libmagisk.so or include libinit-ld.so. Using the DLL copy with such a Magisk package will raise KeyError during extraction instead of producing <workdir>/magisk/ payloads.
  • MagiskOnWSA/…/fixGappsProp.py and MagiskOnWSA/…/fixGappsProp.py overwrite repeated property keys through an ordered dictionary and then regenerate fingerprints from the final values. If an upstream build.prop intentionally carries duplicate keys for precedence, the duplicates are collapsed and Android identity can differ from the source image.
  • MagiskOnWSA/…/post-fs-data.sh deletes every mounted lsp_*.img after running its payload script. If a future payload expects its image to remain available after post-fs-data, it will disappear before later boot phases.