Introduction to Universal Magisk Modules

Magisk revolutionized Android rooting by offering a systemless approach, allowing modifications without altering the `/system` partition directly. This elegant solution paved the way for Magisk Modules, powerful add-ons that can modify nearly any aspect of Android, from system frameworks and libraries to user applications. However, the diverse Android ecosystem—spanning numerous device manufacturers, varying Android versions, and multiple CPU architectures—presents a significant challenge for module developers: ensuring broad compatibility. Building a truly “universal” Magisk module means crafting it to intelligently adapt to the environment it’s installed on, rather than being hardcoded for a specific setup. This guide delves into the advanced techniques required to achieve such universality, making your modules robust and widely usable.

Understanding Core Compatibility Factors

To build a universal module, one must first grasp the primary sources of incompatibility.

Android Version Differences (API Level)

Android versions, identified by their API Level, introduce significant changes that impact modules. These include:

• File Paths: Critical system files and directories might move or change across versions (e.g., from `/system/etc` to `/vendor/etc` or different `/product` partitions).
• SELinux Policies: Security-Enhanced Linux rules are continuously refined, making certain operations permissible on one Android version but blocked on another. Incorrect SELinux contexts can lead to module failure or boot loops.
• Framework Behavior: System services and Java frameworks often have different behaviors or expose different APIs, which can affect modules interacting with them.

CPU Architectures

Android devices ship with various CPU architectures, primarily:

• ARM (32-bit): `armeabi-v7a`
• ARM64 (64-bit): `arm64-v8a`
• x86 (32-bit): `x86`
• x86_64 (64-bit): `x86_64`

If your module includes pre-compiled binaries (e.g., custom `busybox` or a modified `lib` file), you must provide the correct version for each architecture. Running an `arm` binary on an `x86_64` system, or a 32-bit binary on a 64-bit system when a 64-bit version is expected, will result in failure.

Magisk Versioning

Magisk itself evolves. New versions introduce new features, improve stability, and sometimes deprecate old methods. A module relying on an older Magisk API might break on newer Magisk releases, and vice-versa. It’s crucial to account for the `MAGISK_VER_CODE`.

The Universal Module Structure

A standard Magisk module consists of several key files:

• module.prop: Contains metadata like the module’s ID, name, version, author, and crucial compatibility information such as `minMagisk` and `minApi`.
• customize.sh: The most important script for universality. Executed during module installation, it handles device detection, conditional logic, file placement, and necessary modifications.
• post-fs-data.sh: Executed after `/data` is mounted but before Zygote starts. Ideal for early system modifications, `chcon` commands, or patching system properties.
• service.sh: Executed much later during boot, when the system is mostly up. Suitable for long-running services or modifications that don’t need to be active immediately.
• `system` directory: Contains files to be placed in the `/system` partition overlay.
• `vendor` directory: Contains files to be placed in the `/vendor` partition overlay.
• `tools` directory: Often contains architecture-specific binaries used by `customize.sh`.

Implementing Conditional Logic in customize.sh

The `customize.sh` script is where you implement the intelligence to adapt your module. Magisk provides several environment variables during installation that are invaluable for conditional logic.

Detecting Android Version and API Level

Magisk exposes the `API_LEVEL` variable, which corresponds to the Android SDK version. You can use it to apply version-specific patches or file placements.

# Example: Apply a patch only for Android 10 (API 29) and above
if [ "$API_LEVEL" -ge 29 ]; then
  ui_print "- Applying Android 10+ specific patch..."
  # Commands for Android 10+
  install_script "$MODPATH/system_a10plus" "/system"
else
  ui_print "- Applying older Android specific patch..."
  # Commands for older Android versions
  install_script "$MODPATH/system_pre_a10" "/system"
fi

# Example: Specific actions for Android 13 (API 33)
case "$API_LEVEL" in
  33)
    ui_print "- Running Android 13 specific setup."
    # Perform Android 13 unique tasks
    ;; 
  *)
    # Default actions for other versions
    ;;
esac

Adapting for CPU Architecture

The `ARCH` and `IS64BIT` variables are crucial for handling architecture differences.

# Example: Install architecture-specific binary
# Assuming you have binaries in $MODPATH/tools/arm64 and $MODPATH/tools/x86

case "$ARCH" in
  arm)
    cp "$MODPATH/tools/arm/my_tool" "$MODPATH/system/bin/my_tool"
    ;; 
  arm64)
    cp "$MODPATH/tools/arm64/my_tool" "$MODPATH/system/bin/my_tool"
    ;; 
  x86)
    cp "$MODPATH/tools/x86/my_tool" "$MODPATH/system/bin/my_tool"
    ;; 
  x64)
    cp "$MODPATH/tools/x64/my_tool" "$MODPATH/system/bin/my_tool"
    ;; 
  *)
    ui_print "! Unsupported architecture: $ARCH"
    abort "Your device architecture is not supported by this module."
    ;;
esac

# Set permissions
set_perm_recursive 0 0 0755 0644 "$MODPATH/system/bin/my_tool"

# Check if device is 64-bit
if [ "$IS64BIT" = true ]; then
  ui_print "- 64-bit device detected."
  # Perform 64-bit specific operations
else
  ui_print "- 32-bit device detected."
  # Perform 32-bit specific operations
fi

Handling Magisk Version Specifics

Use `MAGISK_VER_CODE` to ensure compatibility with various Magisk releases.

# Example: Check for minimum Magisk version
if [ "$MAGISK_VER_CODE" -lt 23000 ]; then # Magisk v23.0 is 23000
  ui_print "! Your Magisk version ($MAGISK_VER) is too old."
  abort "Please update Magisk to at least v23.0."
fi

# Example: Use new Magisk feature only if available
if [ "$MAGISK_VER_CODE" -ge 24000 ]; then
  ui_print "- Using Magisk v24+ feature..."
  # Commands specific to Magisk v24+
else
  ui_print "- Fallback for older Magisk versions..."
  # Fallback commands
fi

Advanced Techniques for Universality

Dynamic File Placement and Symlinking

Android’s partition layout can vary (e.g., A/B vs. non-A/B, presence of `/product`, `/odm` partitions). Rather than hardcoding paths, detect them or use flexible placement strategies. Magisk’s overlayfs handles most of this, but for specific symlinks or patching, you might need to be more explicit. For instance, if a library might be in `/system/lib` or `/vendor/lib`:

if [ -d "/vendor/lib64" ]; then
  LIBPATH="/vendor/lib64"
elif [ -d "/system/lib64" ]; then
  LIBPATH="/system/lib64"
else
  abort "! Cannot determine 64-bit library path."
fi

# Now copy your library there
cp "$MODPATH/lib/my_lib.so" "$LIBPATH/my_lib.so"
set_perm 0 0 0644 "$LIBPATH/my_lib.so"

SELinux Context Adaptation

Incorrect SELinux contexts are a common cause of boot loops. Magisk’s `set_perm_recursive` and `set_perm` functions handle basic file permissions and ownership, but you might need `chcon` for specific contexts, especially for new files placed in areas that require unique labels. In `post-fs-data.sh`, after files are placed:

# Set specific SELinux context for a custom service executable
chcon u:object_r:system_file:s0 "$MODPATH/system/bin/my_service_daemon"

# Alternatively, use custom sepolicy rules (advanced and requires caution)
# In customize.sh, if you provide a sepolicy.sh:
# if [ -f "$MODPATH/sepolicy.sh" ]; then
#   bash "$MODPATH/sepolicy.sh"
# fi

Be extremely cautious with SELinux modifications, as incorrect rules can compromise security or render the device unbootable. Test extensively!

Pre-compiled Binaries vs. Runtime Compilation

• Pre-compiled: Simplest for users. Requires you to bundle binaries for all supported architectures within your module (`$MODPATH/tools/arm64/mytool`, `$MODPATH/tools/arm/mytool`, etc.). This increases module size but ensures immediate availability.
• Runtime Compilation: Reduces module size. `customize.sh` could download source code and compile on the device using `ndk-build` or `clang` (if available on the system). This is complex, relies on device build tools, and significantly increases installation time and potential failure points. Generally, pre-compiled is preferred for universality unless the binaries are enormous or highly dynamic.

Leveraging Magisk Utility Functions

Magisk provides a `util_functions.sh` script that is sourced by `customize.sh`, offering many helper functions:

• `ui_print “Message”`: Prints messages to the Magisk installation log.
• `abort “Error message”`: Stops installation and prints an error.
• `grep_prop “KEY” “FILE”`: Extracts property values from `.prop` files.
• `cp_ch “SOURCE” “DEST”`: Copies and sets default permissions.
• `rm_rf “PATH”`: Recursively removes files/directories.
• `magiskboot`: A powerful tool for patching boot images directly (use with extreme care).
• `resetprop`: To modify system properties, often used in `post-fs-data.sh`.

# Example using resetprop in post-fs-data.sh
# Hide root detection by spoofing a safetyNet property
resetprop ro.boot.verifiedbootstate "green"
resetprop ro.boot.flash.locked 1

Testing and Debugging Universal Modules

Thorough testing is paramount:

• Emulators: Use Android Studio’s AVD Manager to create emulators for different Android versions and CPU architectures (e.g., API 28 arm64, API 31 x86_64). Install Magisk and your module.
• Physical Devices: Test on a range of actual devices if possible, representing various manufacturers and unique system setups.
• Logging: Verbose `ui_print` statements in `customize.sh`, `post-fs-data.sh`, and `service.sh` are your best friends. Check the Magisk installation log in the Manager app for errors.
• `adb logcat` and `dmesg`: For runtime issues, examine system logs for errors related to your module.
• Magisk Debug Mode: Enable debug mode in Magisk Manager for more detailed logs.

Conclusion

Building universal Magisk modules demands a deep understanding of the Android ecosystem and Magisk’s internal workings. By meticulously considering Android versions, CPU architectures, and Magisk’s own evolution, and by leveraging conditional logic within your `customize.sh` script, you can create robust, adaptable modules. Embrace thorough testing, utilize Magisk’s utility functions, and maintain a cautious approach to system-level modifications like SELinux. The effort invested in achieving universality will result in a module that serves a broader audience and stands the test of time across the fragmented world of Android devices.