Starter bootstrap flow
Overview
The starter module is a minimal Android library whose runtime entry point is starter/…/ServiceStarter.java. It is launched as a privileged app_process Java main, not as an Android component: commandForUserService(...) builds a shell command that sets CLASSPATH to the manager APK, invokes the supplied appProcess binary with /system/bin as the app-process data directory, assigns a --nice-name, and runs moe.shizuku.starter.ServiceStarter with the user-service token, package, class, and caller uid.
ServiceStarter.main(...) prepares the main looper when the privileged process did not already create one, then delegates construction of the app-provided user service to rikka.shizuku.server.UserService.create(args). That API returns the service binder plus the token that must be handed back to the Shizuku manager. If service creation fails, or if the binder cannot be delivered to the manager, the process exits with status 1; otherwise it enters Looper.loop() and stays alive until the manager binder dies.
Binder handoff is done through the manager app's content provider rather than through an exported Android service. ServiceStarter.sendBinder(...) targets authority moe.shizuku.privileged.api.shizuku in user 0, obtains it with ActivityManagerApis.getContentProviderExternal(...), sends a Bundle containing moe.shizuku.privileged.api.intent.extra.BINDER as a moe.shizuku.api.BinderContainer plus ShizukuApiConstants.USER_SERVICE_ARG_TOKEN, and calls provider method sendUserService. The reply is expected to contain another BinderContainer for the Shizuku server/manager binder. ServiceStarter stores that returned binder in the static shizukuBinder field and links a death recipient that terminates the user-service process when Shizuku exits. The content-provider reference is always released with ActivityManagerApis.removeContentProviderExternal(...) in the finally block.
starter/…/IContentProviderCompat.java isolates the hidden IContentProvider.call(...) signature churn across Android releases. Android 12L/API 31+ is called with an AttributionSource built from Os.getuid(), falling back to the API 30 form if the runtime hidden API shape does not match the compile-time stub. API 30 uses (callingPkg, attributionTag, authority, method, arg, extras), API 29 uses (callingPkg, authority, method, arg, extras), and older releases use (callingPkg, method, arg, extras). ServiceStarter passes null for attribution tag and calling package because this privileged-process call only needs to reach the known Shizuku provider authority.
Build and manifest wiring are intentionally small. starter/build.gradle declares the module as an Android library with namespace rikka.shizuku.starter, disables BuildConfig, uses dev.rikka.tools.refine, and depends on :common, :shared, and :server-shared at runtime/implementation scope. It compiles against :provider, libs.hidden.stub, libs.hidden.compat, libs.refine.runtime, and AndroidX annotations so the starter can reference provider/shared binder contracts and hidden framework APIs without declaring app components. starter/…/AndroidManifest.xml is an empty <manifest />, confirming that this module contributes code for privileged process startup rather than activities, services, receivers, or providers.
Coupling
- If
ServiceStarter.USER_SERVICE_CMD_FORMATorcommandForUserService(...)in starter/…/ServiceStarter.java changes, verify the shell caller that executes the returned string still passes--token,--package,--class, and--uidexactly asrikka.shizuku.server.UserService.create(args)expects. The command currently quotes string arguments so shell metacharacters in class names or process suffixes are not expanded before the Java main sees them. - If the manager provider authority, method name, token key, or binder extra changes, update starter/…/ServiceStarter.java and the provider-side handler together. The starter hard-codes authority
moe.shizuku.privileged.api.shizuku, methodsendUserService, extramoe.shizuku.privileged.api.intent.extra.BINDER, andShizukuApiConstants.USER_SERVICE_ARG_TOKEN; a mismatch makes the user service start successfully but fail during binder registration. - If hidden framework stubs or the compile SDK change, re-check starter/…/IContentProviderCompat.java against every supported Android API level. A wrong
IContentProvider.call(...)overload fails at runtime in the privileged process, andServiceStarter.sendBinder(...)treats that as startup failure. - If dependencies in starter/build.gradle move between
implementationandcompileOnly, verify both runtime loading and compile-time hidden API access.:providerandlibs.hidden.stubare compile-only because the privileged process uses the manager APKCLASSPATHand platform classes at runtime, while:common,:shared, and:server-sharedmust be packaged with code used byServiceStarterandUserServicecreation.
Risks
- starter/…/ServiceStarter.java constructs a shell command with interpolated string values. Commit
d1a71ddfixed failures where unquoted class names containing$were expanded by the shell; removing or weakening the current quotes can break nested-class user services or process suffixes with shell-significant characters. - starter/…/ServiceStarter.java relies on the returned Shizuku binder staying strongly referenced in
shizukuBinder. Commit8e0e587fixed user services sometimes not exiting after Shizuku exited by retaining that binder beforelinkToDeath(...); if this is changed back to a local-only reference, the death recipient can be unlinked by garbage collection and orphan the privileged process. - starter/…/ServiceStarter.java has a one-time recovery path for a dead content provider binder: it force-stops
moe.shizuku.privileged.api, waits one second, and retries. Commit5f5d313added this becausegetContentProviderExternal(...)can return a dead provider; removing the retry can make otherwise valid user-service starts fail when the manager provider is in that state.