Introducing a new way to review your PRs.

Read the announcement

rikkaapps / shizuku

Using system APIs directly with adb/root privileges from normal apps through a Java process started with app_process.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / root-build-project-structure

Root build and project structure

Overview

This repository is a Gradle Android multi-project build. settings.gradle is the module wiring entry point: it registers the local modules :server, :starter, :shell, :manager, and :common, then registers API-related modules from a configurable API root as :aidl, :rish, :shared, :api, :provider, :server-shared, and :hidden-api-stub.

The API root defaults to the api directory, which is declared as the RikkaApps/Shizuku-API submodule in .gitmodules. settings.gradle can instead point those API-backed projects at another checkout when local.properties contains api.useLocal=true and an api.dir value. In that mode, the included Gradle project names stay the same, but their projectDir values move from api/<module> to <api.dir>/<module>. The checked-out api directory is empty in this worktree, so the external submodule content must be initialized before the default build can resolve those project directories or the root api/manifest.gradle script.

Plugin and dependency repository policy is centralized in settings.gradle. Plugin resolution uses google(), mavenLocal(), and mavenCentral() and pins the Android Gradle plugin to 8.10.1, Kotlin Android to 2.1.21, and the Rikka build plugins used by downstream modules. Dependency resolution sets RepositoriesMode.FAIL_ON_PROJECT_REPOS, so Android modules must use the root repositories rather than declaring their own; the only extra Maven repository is JitPack, restricted to com.github.topjohnwu.libsu. The root version catalog defines the hidden API and refine coordinates used by child projects.

build.gradle applies only the IDEA plugin at the root, excludes out from IDE indexing, and configures every subproject that applies com.android.base. That shared Android block sets compileSdk = 36, build tools 36.0.0, NDK 29.0.13113456, minSdk = 24, targetSdk = 36, and Java source/target compatibility VERSION_21. Because this configuration is guarded by plugins.withId("com.android.base"), it affects Android application and library modules after their Android plugin is applied without requiring each module to repeat those values.

The root build also applies api/manifest.gradle from build.gradle, then derives global ext.versionCode and ext.versionName from git history. versionCode is git rev-list --count HEAD, and versionName is based on api_version_major from the API manifest script, the literal minor string .6.0, the commit count, and git rev-parse --short HEAD. A build therefore needs both a usable Git checkout and readable API manifest script content.

Global Gradle properties live in gradle.properties: the Gradle daemon gets -Xmx2048m and UTF-8 file encoding, AndroidX is enabled, and Android resource IDs are configured as transitive and final through android.nonTransitiveRClass=false and android.nonFinalResIds=false. The wrapper files gradlew, gradlew.bat, gradle/wrapper/gradle-wrapper.jar, and gradle/wrapper/gradle-wrapper.properties pin command-line builds to Gradle 8.14 and require a Java runtime; CI supplies Java 21 explicitly.

Signing is centralized in signing.gradle for modules that apply it. It reads root signing.properties and fills the android.signingConfigs.sign keystore fields from KEYSTORE_FILE, KEYSTORE_PASSWORD, KEYSTORE_ALIAS, and KEYSTORE_ALIAS_PASSWORD. If that file is absent, it copies the debug signing config into sign, allowing local release-like builds without private keys. .gitignore excludes both root signing.properties and manager/signing.properties, along with local Gradle, IDE, native build, and output directories.

The GitHub Actions build entry point is .github/…/app.yml. On push, it checks out submodules recursively with full history, installs Temurin Java 21, writes root signing.properties and key.jks from secrets only on master, enables Gradle dependency graph and build scans, appends CI-only Android/Gradle properties, and runs ./gradlew :manager:assemble. The artifact upload expects APK outputs under manager/build/outputs and derives the artifact name from the release APK filename. .github/…/config.yml and .github/…/bug_report.yml only affect GitHub issue intake and are ignored by the workflow trigger path filter.

Line-ending and local-file conventions are set at the root. .gitattributes normalizes text to LF, keeps *.bat files CRLF, and treats *.jar as binary, which matters for the checked-in Gradle wrapper jar and Windows launcher. .gitignore keeps local.properties untracked; this protects developer-specific SDK paths and the optional local API checkout override that settings.gradle reads.

Coupling

  • If settings.gradle changes the API module names or their projectDir mapping, also update .gitmodules, .github/…/app.yml, and the root build.gradle apply from: 'api/manifest.gradle' assumption. CI currently checks out the api submodule recursively and the root build expects api/manifest.gradle to exist at that path unless local.properties overrides the API root locally.
  • If the Android Gradle plugin, Gradle wrapper, or Java compatibility changes in settings.gradle, gradle/wrapper/gradle-wrapper.properties, or build.gradle, verify .github/…/app.yml still installs a compatible Java version. The shared build.gradle block compiles all Android modules with Java 21, and CI currently supplies Temurin 21 before invoking ./gradlew :manager:assemble.
  • If repository policy changes in settings.gradle, verify child module build files do not declare project-local repositories. RepositoriesMode.FAIL_ON_PROJECT_REPOS makes such declarations fail the build rather than silently adding repositories.
  • If versioning changes in root build.gradle or the API manifest script, verify CI still uses fetch-depth: 0 in .github/…/app.yml. The root version code and name are computed from Git commit count and short SHA, so shallow checkout history would change or break release versioning.
  • If signing property names or paths change in signing.gradle, update .github/…/app.yml and .gitignore together. CI writes root signing.properties with the exact keys consumed by signing.gradle, and .gitignore prevents those generated secrets from being committed.

Risks

  • build.gradle unconditionally applies api/manifest.gradle. If the api submodule is not initialized or a local API override is expected but only configured in local.properties, the root build can fail before any Android module is configured because that script is missing from the default api path.
  • settings.gradle calls props["api.useLocal"].equals("true"). If local.properties exists but omits api.useLocal, settings evaluation can fail with a null dereference before modules are included; developers using local.properties for ordinary Android SDK settings should include the key or avoid this override block.
  • .github/…/app.yml derives releaseName by shelling out to ls manager/build/outputs/apk/release/shizuku*-v*-release.apk and parsing with awk. If the manager APK naming pattern changes, the build can succeed but artifact naming/upload metadata can break.