docs/android_isolated_splits.md - chromium/src.git - Git at Google

 # Isolated Splits

 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].

 [TOC]

 ## About

 ### What are Isolated Splits?

 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.

 [android:isolatedSplits]: https://developer.android.com/reference/android/R.attr#isolatedSplits

 ### Why use Isolated Splits?

 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.

 ### What Splits Exist in Chrome?

 Chrome's splits look like:

 ```
 base.apk <-- chrome.apk <-- image_editor.apk
                         <-- feedv2.apk
                         <-- ...
 ```

 * The browser process loads the `chrome` split on start-up, and other splits are
   loaded on-demand.
 * Renderer and GPU processes do not load any feature splits.
   * The `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.

 ### How are Isolated Splits Loaded?

 There are two ways:
 1) They can be loaded by Android Framework when handling an intent.
    * E.g.: If a feature split defines an Activity in its manifest, Android
      will create the split's Context and associate the Activity with it.
 2) They can be loaded explicitly via [BundleUtils.createIsolatedSplitContext()].
    * The most common way to load in this way is through declaring a
      `ModuleInterface`, as described in [android_dynamic_feature_modules.md].

 [BundleUtils.createIsolatedSplitContext()]: https://source.chromium.org/search?q=func:createIsolatedSplitContext&ss=chromium
 [android_dynamic_feature_modules.md]: android_dynamic_feature_modules.md

 ## OS Support for Isolated Splits

 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.

 ## OS Bugs

 ### Base ClassLoader used for Services in Splits (Android Pre-S)

 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.

 [b/169196314]: https://issuetracker.google.com/169196314
 [SplitCompatService]: https://source.chromium.org/search?q=symbol:SplitCompatService&ss=chromium
 [compile-time check]: https://source.chromium.org/chromium/chromium/src/+/main:build/android/gyp/create_app_bundle.py;l=446;drc=c4dd266492ad1e242161b415ac5a1d9fccd7a041

 ### Corrupted .odex (Android O MR1)

 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.

 [preemptively run]: https://source.chromium.org/search?q=symbol:DexFixer.needsDexCompile&ss=chromium
 [PackageReplacedBroadcastReceiver]: https://source.chromium.org/search?q=symbol:PackageReplacedBroadcastReceiver&ss=chromium

 ### Conflicting ClassLoaders #1

 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()].

 [b/172602571]: https://issuetracker.google.com/172602571
 [detect and crash early]: https://source.chromium.org/search?q=crbug.com%2F1146745&ss=chromium
 [AppComponentFactory]: https://developer.android.com/reference/android/app/AppComponentFactory
 [detect and fix]: https://source.chromium.org/search?q=f:splitcompatappcomponentfactory&ss=chromium
 [ChromeBaseAppCompatActivity.attachBaseContext()]: https://source.chromium.org/search?q=BundleUtils\.checkContextClassLoader&ss=chromium

 ### Conflicting ClassLoaders #2

 Tracked by [b/172602571], when a new split language split or feature split is
 installed, the ClassLoaders for non-base splits are recreated. Any reference to
 a class from the previous ClassLoader (e.g. due to native code holding
 references to them) will result in `ClassCastExceptions` where
 `"TypeA cannot be cast to TypeA"`.

 **Work-around:**

 There is no work-around. This is a source of crashes. We could potentially
 mitigate by restarting chrome when a split is installed.

 ### System.loadLibrary() Broken for Libraries in Splits

 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.

 ```java
 System.load(BundleUtils.getNativeLibraryPath("foo", "mysplitsname"));
 ```

 [b/171269960]: https://issuetracker.google.com/171269960

 ### System.loadLibrary() Unusable from Split if Library depends on Another Loaded by Base Split

 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.

 ### System.loadLibrary() Broken for Libraries in Splits on System Image

 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.

 ### Too Many Splits Break App Zygote

 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]).

 [crbug/1298496]: https://bugs.chromium.org/p/chromium/issues/detail?id=1298496
 [Application Zygote]: https://developer.android.com/reference/android/app/ZygotePreload

 ### AppComponentFactory does not Hook Split ClassLoaders

 `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.

 [b/265583114]: https://issuetracker.google.com/265583114

 ### Incorrect Handling of Shared Libraries

 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:**

  * Always add `<uses-library>` to the base split.

 [b/265589431]: https://issuetracker.google.com/265589431

 ## Other Quirks & Subtleties

 ### System Image APKs

 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:
 ```sh
 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.

 ### Chrome's Application ClassLoader

 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.

 [use reflection]: https://source.chromium.org/search?q=f:SplitChromeApplication%20replaceClassLoader&ss=chromium

 ### ContentProviders

 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.

 [compile-time check]: https://source.chromium.org/search?q=symbol:_MaybeCheckServicesAndProvidersPresentInBase&ss=chromium
 [SplitCompatContentProvider]: https://source.chromium.org/search?q=symbol:SplitCompatContentProvider&ss=chromium

 ### JNI and ClassLoaders

 When you call from native-&gt;Java (via `@CalledByNative`), there are two APIs
 that Chrome could use to resolve the target class:

 1) JNI API: [JNIEnv::FindClass()]
 2) Java Reflection API:`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.

 [JNIEnv::FindClass()]: https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp16027

 ### Accessing Android Resources

 When resources live in a split, they must be accessed through a Context object
 associated with that split. However:

 * Bug: Chrome's build system [improperly handles ID conflicts] between splits.
 * Bug: Splash screens [fail to load] for activities in Isolated Splits (unless
   associated resources are defined in the base split).
 * Quirk: `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.

 [stores all Android resources in the base split]: https://source.chromium.org/search?q=recursive_resource_deps%5C%20%3D%5C%20true
 [improperly handles ID conflicts]: https://crbug.com/1133898
 [fail to load]: https://issuetracker.google.com/171743801
 [a crbug]: https://crbug.com/1165782

 ### Inflating Layouts

 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()]

 [BundleUtils.createContextForInflation()]: https://source.chromium.org/search?q=symbol:BundleUtils.createContextForInflation&ss=chromium

 ### onRestoreInstanceState with Classes From Splits

 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].

 [`onSaveInstanceState`]: https://source.chromium.org/search?q=symbol:ChromeBaseAppCompatActivity.onSaveInstanceState&ss=chromium
 [a custom ClassLoader]: https://source.chromium.org/search?q=symbol:ChromeBaseAppCompatActivity.getClassLoader&ss=chromium
 [b/260574161]: https://issuetracker.google.com/260574161

 ### Package Private Methods

 Due to having different ClassLoaders, package-private methods don't work across
 the boundary, even though they will compile. Release builds will fail during
 the R8 step, which has a check for cross-split package-private access.

 **Work around:**

 Make any method public that you wish to call in another module, even if it's in
 the same package.

 ### Proguarding Splits

 "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).

 [proguard.py]: https://source.chromium.org/search?q=symbol:_DeDupeInputJars%20f:proguard.py&ss=chromium
 [b/225876019]: https://issuetracker.google.com/225876019

 ### Metadata in Splits

 Metadata is queried on a per-app basis (not a per-split basis). E.g.:

 ```java
 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.

 ## Other Resources

  * [go/isolated-splits-dev-guide] (Googlers only).
  * [go/clank-isolated-splits-architecture] (Googlers only).

 [go/isolated-splits-dev-guide]: http://go/isolated-splits-dev-guide
 [go/clank-isolated-splits-architecture]: http://go/clank-isolated-splits-architecture
	# Isolated Splits

	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].

	[TOC]

	## About

	### What are Isolated Splits?

	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.

	[android:isolatedSplits]: https://developer.android.com/reference/android/R.attr#isolatedSplits

	### Why use Isolated Splits?

	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.

	### What Splits Exist in Chrome?

	Chrome's splits look like:

	```
	base.apk <-- chrome.apk <-- image_editor.apk
	<-- feedv2.apk
	<-- ...
	```

	* The browser process loads the `chrome` split on start-up, and other splits are
	loaded on-demand.
	* Renderer and GPU processes do not load any feature splits.
	* The `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.

	### How are Isolated Splits Loaded?

	There are two ways:
	1) They can be loaded by Android Framework when handling an intent.
	* E.g.: If a feature split defines an Activity in its manifest, Android
	will create the split's Context and associate the Activity with it.
	2) They can be loaded explicitly via [BundleUtils.createIsolatedSplitContext()].
	* The most common way to load in this way is through declaring a
	`ModuleInterface`, as described in [android_dynamic_feature_modules.md].

	[BundleUtils.createIsolatedSplitContext()]: https://source.chromium.org/search?q=func:createIsolatedSplitContext&ss=chromium
	[android_dynamic_feature_modules.md]: android_dynamic_feature_modules.md

	## OS Support for Isolated Splits

	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.

	## OS Bugs

	### Base ClassLoader used for Services in Splits (Android Pre-S)

	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.

	[b/169196314]: https://issuetracker.google.com/169196314
	[SplitCompatService]: https://source.chromium.org/search?q=symbol:SplitCompatService&ss=chromium
	[compile-time check]: https://source.chromium.org/chromium/chromium/src/+/main:build/android/gyp/create_app_bundle.py;l=446;drc=c4dd266492ad1e242161b415ac5a1d9fccd7a041

	### Corrupted .odex (Android O MR1)

	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.

	[preemptively run]: https://source.chromium.org/search?q=symbol:DexFixer.needsDexCompile&ss=chromium
	[PackageReplacedBroadcastReceiver]: https://source.chromium.org/search?q=symbol:PackageReplacedBroadcastReceiver&ss=chromium

	### Conflicting ClassLoaders #1

	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()].

	[b/172602571]: https://issuetracker.google.com/172602571
	[detect and crash early]: https://source.chromium.org/search?q=crbug.com%2F1146745&ss=chromium
	[AppComponentFactory]: https://developer.android.com/reference/android/app/AppComponentFactory
	[detect and fix]: https://source.chromium.org/search?q=f:splitcompatappcomponentfactory&ss=chromium
	[ChromeBaseAppCompatActivity.attachBaseContext()]: https://source.chromium.org/search?q=BundleUtils\.checkContextClassLoader&ss=chromium

	### Conflicting ClassLoaders #2

	Tracked by [b/172602571], when a new split language split or feature split is
	installed, the ClassLoaders for non-base splits are recreated. Any reference to
	a class from the previous ClassLoader (e.g. due to native code holding
	references to them) will result in `ClassCastExceptions` where
	`"TypeA cannot be cast to TypeA"`.

	Work-around:

	There is no work-around. This is a source of crashes. We could potentially
	mitigate by restarting chrome when a split is installed.

	### System.loadLibrary() Broken for Libraries in Splits

	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.

	```java
	System.load(BundleUtils.getNativeLibraryPath("foo", "mysplitsname"));
	```

	[b/171269960]: https://issuetracker.google.com/171269960

	### System.loadLibrary() Unusable from Split if Library depends on Another Loaded by Base Split

	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.

	### System.loadLibrary() Broken for Libraries in Splits on System Image

	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.

	### Too Many Splits Break App Zygote

	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]).

	[crbug/1298496]: https://bugs.chromium.org/p/chromium/issues/detail?id=1298496
	[Application Zygote]: https://developer.android.com/reference/android/app/ZygotePreload

	### AppComponentFactory does not Hook Split ClassLoaders

	`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.

	[b/265583114]: https://issuetracker.google.com/265583114

	### Incorrect Handling of Shared Libraries

	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:

	* Always add `<uses-library>` to the base split.

	[b/265589431]: https://issuetracker.google.com/265589431

	## Other Quirks & Subtleties

	### System Image APKs

	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:
	```sh
	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.

	### Chrome's Application ClassLoader

	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.

	[use reflection]: https://source.chromium.org/search?q=f:SplitChromeApplication%20replaceClassLoader&ss=chromium

	### ContentProviders

	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.

	[compile-time check]: https://source.chromium.org/search?q=symbol:_MaybeCheckServicesAndProvidersPresentInBase&ss=chromium
	[SplitCompatContentProvider]: https://source.chromium.org/search?q=symbol:SplitCompatContentProvider&ss=chromium

	### JNI and ClassLoaders

	When you call from native->Java (via `@CalledByNative`), there are two APIs
	that Chrome could use to resolve the target class:

	1) JNI API: [JNIEnv::FindClass()]
	2) Java Reflection API:`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.

	[JNIEnv::FindClass()]: https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp16027

	### Accessing Android Resources

	When resources live in a split, they must be accessed through a Context object
	associated with that split. However:

	* Bug: Chrome's build system [improperly handles ID conflicts] between splits.
	* Bug: Splash screens [fail to load] for activities in Isolated Splits (unless
	associated resources are defined in the base split).
	* Quirk: `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.

	[stores all Android resources in the base split]: https://source.chromium.org/search?q=recursive_resource_deps%5C%20%3D%5C%20true
	[improperly handles ID conflicts]: https://crbug.com/1133898
	[fail to load]: https://issuetracker.google.com/171743801
	[a crbug]: https://crbug.com/1165782

	### Inflating Layouts

	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()]

	[BundleUtils.createContextForInflation()]: https://source.chromium.org/search?q=symbol:BundleUtils.createContextForInflation&ss=chromium

	### onRestoreInstanceState with Classes From Splits

	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].

	[`onSaveInstanceState`]: https://source.chromium.org/search?q=symbol:ChromeBaseAppCompatActivity.onSaveInstanceState&ss=chromium
	[a custom ClassLoader]: https://source.chromium.org/search?q=symbol:ChromeBaseAppCompatActivity.getClassLoader&ss=chromium
	[b/260574161]: https://issuetracker.google.com/260574161

	### Package Private Methods

	Due to having different ClassLoaders, package-private methods don't work across
	the boundary, even though they will compile. Release builds will fail during
	the R8 step, which has a check for cross-split package-private access.

	Work around:

	Make any method public that you wish to call in another module, even if it's in
	the same package.

	### Proguarding Splits

	"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).

	[proguard.py]: https://source.chromium.org/search?q=symbol:_DeDupeInputJars%20f:proguard.py&ss=chromium
	[b/225876019]: https://issuetracker.google.com/225876019

	### Metadata in Splits

	Metadata is queried on a per-app basis (not a per-split basis). E.g.:

	```java
	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.

	## Other Resources

	* [go/isolated-splits-dev-guide] (Googlers only).
	* [go/clank-isolated-splits-architecture] (Googlers only).

	[go/isolated-splits-dev-guide]: http://go/isolated-splits-dev-guide
	[go/clank-isolated-splits-architecture]: http://go/clank-isolated-splits-architecture