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 <-- 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.
Tracked by b/172602571, sometimes a split‘s parent ClassLoader is 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).
Tracked by UMA Android.IsolatedSplits.ClassLoaderReplaced. Occurs < 0.05% of the time.
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"));
Also tracked by b/171269960, maybe related to linker namespaces. If a split tries to load libfeature.so, and libfeature.so has a DT_NEEDED entry for libbase.so, and libbase.so is loaded by the base split, then the load will fail.
Work-around:
Have base split load libraries from within splits. Proxy all JNI calls through a class that exists in the base split.
Also tracked by b/171269960, Android‘s linker config (ld.config.txt) sets permitted_paths="/data:/mnt/expand", and then adds the app’s .apk to an allowlist. This allowlist does not contain apk splits, so library loading is blocked by permitted_paths when the splits live on the /system partition.
Work-around:
Use compressed system image stubs (.apk.gz and -Stub.apk) so that Chrome is extracted to the /data partition upon boot.
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).
AppComponentFactory#instantiateClassLoader() is meant to allow apps to hook ClassLoader creation. The hook is called for the base split, but not for other isolated splits. Tracked by b/265583114. There is no work-around.
Tracked by [b/265589431]. If an APK split has <uses-library> in its manifest, the classloader for the split is meant to have that library added to it by the framework. However, Android does not add the library to the classpath when a split is dynamically installed, but instead adds it to the classpath of the base split's classloader upon subsequent app launches.
Work-around:
In progress: https://bugs.chromium.org/p/chromium/issues/detail?id=1066842#c34
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, RecyclerViews, and potentially other classes from splits. Upon re-launch, these class names are used to reflectively instantiate instances. FragmentManager uses the ClassLoader of the Activity to instantiate them, and RecyclerView uses the ClassLoader associated with the Bundle object. The reflection fails if the active Activity resides in a different spilt from the reflectively instantiated classes.
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. The custom ClassLoader is passed to Bundle instances in ChromeBaseAppCompatActivity.onRestoreInstanceState().
Having Android Framework call Bundle.setClassLoader() is tracked in b/260574161.
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).
Metadata is queried on a per-app basis (not a per-split basis). E.g.:
ApplicationInfo ai = context.getPackageManager().getApplicationInfo(context.getPackageName(), PackageManager.GET_META_DATA); Bundle b = ai.metaData;
This bundle contains merged values from all fully-installed apk splits.