This doc aims to explain the ins and outs of using Isolated Splits on Android.
For an overview of apk splits and how to use them in Chrome, see android_dynamic_feature_modules.md.
Isolated Splits is an opt-in feature (via android:isolatedSplits manifest entry) that cause all feature splits in an application to have separate Context
objects, rather than being merged together into a single Application Context
. The Context
objects have distict ClassLoader
and Resources
instances. They are loaded on-demand instead of eagerly on launch.
With Isolated Splits, each feature split is loaded in its own ClassLoader, with the parent split set as the parent ClassLoader.
The more DEX that is loaded on start-up, the more RAM and time it takes for application code to start running. Loading less code on start-up is particularly helpful for Chrome, since Chrome tends to spawn a lot of processes, and because renderer processes require almost no DEX.
Chrome's splits look like:
base.apk <-- chrome.apk <-- autofill_assistant.apk <-- image_editor.apk <-- feedv2.apk <-- ...
chrome
split on start-up, and other splits are loaded on-demand.chrome
split exists to minimize the amount of DEX loaded by renderer processes. However, it also enables faster browser process start-up by allowing DEX to be loaded concurrently with other start-up tasks.There are two ways:
ModuleInterface
, as described in android_dynamic_feature_modules.md.Initial support was added in Android O. On earlier Android versions, all feature splits are loaded during process start-up and merged into the Application Context.
Service Contexts are created with the base split‘s ClassLoader rather than the split’s ClassLoader.
Fixed in Android S. Bug: b/169196314 (Googler only).
Work-around:
We use SplitCompatService (and siblings) to put a minimal service class in the base split. They forward all calls to an implementation class, which can live in the chrome
split (or other splits). We also have a compile-time check to enforce that no Service subclasses exist outside of the base split.
Android O MR1 has a bug where bg-dexopt-job
(runs during maintenance windows) breaks optimized dex files for Isolated Splits. The corrupt .odex
files cause extremely slow startup times.
Work-around:
We preemptively run dexopt
so that bg-dexopt-job
decides there is no work to do. We trigger this from PackageReplacedBroadcastReceiver so that it happens whenever Chrome is updated rather than when the user launches Chrome.
Missing synchronization can cause the parent ClassLoader of split contexts to be different from the Application's ClassLoader. This manifests as odd-looking ClassCastExceptions
where "TypeA cannot be cast to TypeA"
(since the two TypeAs
are from different ClassLoaders).
Fixed in Android S. Bug: b/172602571 (Googler only).
Work-around:
On Android O, there is no work-around. We just detect and crash early.
Android P added AppComponentFactory, which offers a hook that we use to detect and fix ClassLoader mixups. The ClassLoader mixup also needs to be corrected for ContextImpl
instances, which we do via ChromeBaseAppCompatActivity.attachBaseContext().
Tracked by b/171269960, Android is not adding the apk split to the associated ClassLoader's nativeSearchPath
. This means that libfoo.so
within an isolated split is not found by a call to System.loadLibrary("foo")
.
Work-around:
Load libraries via System.load()
instead.
System.load(BundleUtils.getNativeLibraryPath("foo", "mysplitsname"));
Starting with Android Q / TriChrome, Chrome uses an Application Zygote. As part of initialization, Chrome‘s ApplicationInfo
object is serialized into a fixed size buffer. Each installed split increases the size of the ApplicationInfo
object, and can push it over the buffer’s limit.
Work-around:
Do not add too many splits, and monitor the size of our ApplicationInfo
object (crbug/1298496).
When distributing Chrome on Android system images, we generate a single .apk
file that contains all splits merged together (or rather, all splits whose AndroidManifest.xml
contain <dist:fusing dist:include="true" />
). We do this for simplicity; Android supports apk splits on the system image.
You can build Chrome's system .apk
via:
out/Release/bin/trichrome_chrome_bundle build-bundle-apks --output-apks SystemChrome.apks --build-mode system unzip SystemChrome.apks system/system.apk
Shipping a single .apk
file simplifies distribution, but eliminates all the benefits of Isolated Splits.
A lot of Chrome‘s code uses the ContextUtils.getApplicationContext()
as a Context object. Rather than auditing all usages and replacing applicable ones with the chrome
split’s Context, we use reflection to change the Application instance‘s ClassLoader to point to the chrome
split’s ClassLoader.
Unlike other application components, ContentProviders are created on start-up even when they are not the reason the process is being created. If a ContentProvider were to be declared in a split, its split's Context would need to be loaded during process creation, eliminating any benefit.
Work-around:
We declare all ContentProviders in the base split's AndroidManifest.xml
and enforce this with a compile-time check. ContentProviders that would pull in significant amounts of code use SplitCompatContentProvider to delegate to a helper class living within a split.
When you call from native->Java (via @CalledByNative
), there are two APIs that Chrome could use to resolve the target class:
ClassLoader.loadClass())
Chrome uses #2. For methods within feature splits, generate_jni()
targets use split_name = "foo"
to make the generated JNI code use the split's ClassLoader.
When resources live in a split, they must be accessed through a Context object associated with that split. However:
RemoteViews
, notification icons, and other Android features that access resources by Package ID require resources to be in the base split when Isolated Splits are enabled.Work-around:
Chrome stores all Android resources in the base split. There is a crbug to track moving resources into splits, but it may prove too challenging.
Layouts should be inflated with an Activity Context so that configuration-specific resources and themes are used. If layouts contain references to View classes from different feature splits than the Activity‘s, then the views’ split ClassLoaders must be used.
Work-around:
Use the ContextWrapper
created via: BundleUtils.createContextForInflation()
When Android kills an app, it normally calls onSaveInstanceState()
to allow the app to first save state. The saved state includes the class names of active Fragments. Upon re-launch, these class names are used to reflectively instantiate the fragments. FragmentManager
uses the ClassLoader of the Activity to instantiate them, which doesn't work if the Activity and fragment classes live in different splits.
Work-around:
Chrome stores the list of all splits that have been used for inflation during onSaveInstanceState and then uses a custom ClassLoader to look within them for classes that do not exist in the application's ClassLoader.
Due to having different ClassLoaders, package-private methods don't work across the boundary, even though they will compile.
Work around:
Make any method public that you wish to call in another module, even if it's in the same package.
“Proguarding” is the build step that performs whole-program optimization of Java code, and “R8” is the program Chrome uses to do this. R8 currently supports mapping input .jar
files to output feature splits. If two feature splits share a common GN dep
, then its associated .jar
will be promoted to the parent split (or to the base split) by our proguard.py wrapper script.
This scheme means that if a single class from a large library is needed by, or promoted to, the base split, then every class needed from that library by feature splits will also remain in the base split. The feature request to have R8 move code into deeper splits on a per-class basis is b/225876019 (Googler only).