# Binary Size Explainer
This document explains the overhead of each kind of binary size, where
"overhead" is the performance cost of existing (e.g. does not include the
overhead of loading an image, just the overhead of an image existing). This
document focuses on Android, but several types of size are the same on other
platforms.
*** note
See [optimization_advice.md] for ideas on how to reduce
size.
***
[optimization_advice.md]: optimization_advice.md
[TOC]
## How big is Chrome?
* Chrome's per-commit size is tracked in [chromeperf](https://chromeperf.appspot.com/report):
* For Android, look for "resource\_sizes".
* Googlers, see also [go/chromeapksizes], and [go/chromemilestonesizes].
* For other platforms: look for "sizes".
* As of 2019, Chrome for Android (arm32) grows by about 100kb per week.
* To get a feeling for how large individual features are, open a
[milestone size breakdown] and group by "Component" (Googlers only).
* For non-googlers, run `//tools/binary_size/supersize archive` on a release
build to create a `.size` file, and upload it to [the viewer].
[go/chromeapksizes]: http://go/chromeapksizes
[go/chromemilestonesizes]: http://go/chromemilestonesizes
[milestone size breakdown]: https://goto.google.com/chrome-supersize
[the viewer]: https://chrome-supersize.firebaseapp.com/viewer.html
## Why care about binary size?
* Takes disk space away from users.
* Much less so than Chrome's cache, but this is space that cannot be
cleared, and on Android is displayed prominently in the Play Store and in
system settings.
* Takes disk space on system images for Android and Chrome OS.
* It routinely happens that system images fill up, and all components need
to do their part to fit into the space.
* Binary size is a "proxy metric" for other performance metrics.
* It's a metric that is trivial to measure, and correlates to RAM usage,
start-up speed etc. (there are nuances, which we try to capture in this
doc).
* Binary size affects users' perception of Chrome's performance.
* E.g. Large app size leads users to think Chrome is "bloated".
* Binary size is much easier to stay on top of than it is to retroactively fix.
Googlers - see [go/chromebinarysizematters] for more links to studies.
[go/chromebinarysizematters]: http://go/chromebinarysizematters
### How much effort should I spend to reduce binary size?
Chrome is currently not under any hard growth limits, but to mitigate
unnecessary bloat of this shared resource, everyone should ensure that
reasonable diligence is taken to minimize growth.
* "Reasonable diligence" requires judgement and varies depending on the change.
A rough guideline:
* For small (<50kb) increases: spend a day trying to reduce (unless it's obviously not possible).
* For larger increases: Try to understand and document why the change requires so much size.
* If you are unsure, reach out on [binary-size@] for advice.
* The [android-binary-size][size_trybot] trybot will alert for single commits that increase
binary size on 32-bit Android by more than 16kb.
* While such increases are often fine, this helps prevent unexpected
increases.
* It typically takes about a week of engineering time to reduce Android's binary size by 50kb.
[binary-size@]: https://groups.google.com/a/chromium.org/g/binary-size/
[size_trybot]: /docs/speed/binary_size/android_binary_size_trybot.md
## How Chrome is Packaged
### WebView vs Chrome
Android WebView is used by the majority of Android apps, so overhead (other
than clean memory) introduced into WebView has a multiplicative effect on the
OS. See
[android\_build\_instructions.md]
for how packaging of Chrome / WebView changes by OS version.
[android\_build\_instructions.md]: /docs/android_build_instructions.md#Multiple-Chrome-Targets
### APK Splits
Chrome ships as an [Android App Bundle], and consists of several APK splits.
[Android App Bundle]: /docs/android_dynamic_feature_modules.md#about-bundles
#### The "base" split
* Loaded on start-up by every process.
* Keeping its dex size minimal is crucial, since it has both RAM and start-up
overhead _per-renderer_.
#### In the "chrome" feature split
* Loaded on start-up by the browser process.
* Important to keep dex size small in order to have Chrome start-up quickly,
and to minimize our baseline memory requirement.
#### In another feature split
* Since they are loaded on-demand, binary size matters proportionally to the
number of users that use the module.
#### In a DFM
* These are feature splits that are not even downloaded until needed. Binary
size matters proportionally to the number of users that use the module.
## Types of Overhead
Here we define some terms used to describe overhead.
**Clean Memory:**
* Backed by a file on disk, and mapped to virtual memory via `mmap()`.
* Shared between processes.
* Paged into RAM on-demand by the OS.
* Fast when disk cache is hot, and slower when disk cache is cold.
**Dirty Memory:**
* Not backed by a file, and thus cannot be safely paged out (except to zram)
## Overhead for Each Type of Binary Size
### Native code Size
#### Code (.text)
Machine instructions.
* **RAM:** _Clean Memory_, with good locality thanks to PGO.
* **Start-up:** No effect beyond page faults.
#### Read-only Data (.rodata)
String literals, global constants, etc.
* **RAM:** _Clean Memory_, with poor locality (most is paged in after a short amount of time)
* **Start-up:** No effect beyond page faults.
#### Read-only-after-relocated Data (.data.rel.ro)
Read-only data that must be adjusted based on the base load address of the executable.
* **RAM:** _Dirty-ish Memory_. It's complicated. Refer to
[native_relocations.md].
* **Start-up:** Some overhead. Again, read the linked doc.
[native relocations.md]: /docs/native_relocations.md#why-do-they-matter
#### Mutable Data (.data)
Global non-const variables.
* **RAM:** _Dirty Memory_
* **Start-up:** The entire section is loaded before any code is run.
### Native resources (.pak)
UI Images, chrome:// pages, UI strings, etc.
* **RAM:** _Clean Memory_
* **Start-up:** Platform-dependent. None on Android. Page faults on desktop.
* Locality improved [using an orderfile] on some platforms.
[using an orderfile]: /tools/gritsettings/README.md#:~:text=internal%20translation%20process.-,startup_resources_%5Bplatform%5D.txt,-%3A%20These%20files%20provide
### Android: Java code size (.dex)
Java bytecode in the [DEX file format], stored in `classes.dex`, `classes2.dex`,
... When Android installs Chrome, this bytecode is turned into machine code and
stored as `.odex` & `.vdex` files. The size of these files depends on the OS
version and dex compilation profile. Generally, they are 1x the size of
uncompressed `.dex` on Android Go, and 4x the size of uncompressed `.dex` on
other devices.
* **RAM:** Mostly _Clean Memory_, but Some _Dirty Memory_ as well.
* E.g.: The number of method declarations (referred to as "method count")
directly corresponds to dirty RAM, where 1 entry = 4 bytes (on arm32).
* **Start-up:** Impact proportional to overall size. Mitigated by packaging
code into [feature splits] when possible.
[DEX file format]: https://source.android.com/devices/tech/dalvik/dex-format
[feature splits]: /docs/android_dynamic_feature_modules.md#:~:text=files%2C%20known%20as%20%E2%80%9C-,feature%20splits,-%E2%80%9D.%20Feature%20splits%20have
#### More about Method Count
When changing `.java code`, the change in method count is
[shown in code reviews][size_trybot]. The count is the number of method
references added/removed after optimization. Which methods are added/removed
can be seen in the "APK Breakdown" link by checking "Method Count Mode".
Method count is a useful thing to look at because:
* Each method reference has overhead within the dex file format, and for smallish methods, contributes more to binary size than its corresponding executable code.
* Method references that survive R8 optimization show how optimizable your abstractions are. Try to use low-overhead (or zero-overhead) abstractions. If you find that you're adding a lot of methods, you should see whether a different abstraction would result in fewer methods.
### Android: Resources
#### resources.arsc
All files within `res/`, as well as individual entries with `res/values` files
contribute to this file. It consists of a string table, plus one 2D array
for each resource type (strings, drawable, etc). The overhead (not included
actual data) for each table is: `# [unique configs] * # of resources * sizeof(entry)`.
* **RAM:** _Clean Memory_, with poor locality (most is paged in after a short
amount of time)
* **Start-up:** No effect beyond page faults.
* Its table-based file format means it's important to keep the number of unique
configs as small as possible.
[unique configs]: https://developer.android.com/guide/topics/resources/providing-resources#QualifierRules
#### res/... (drawables/layouts/xml)
Files that are packaged within the `res/` directory of the `.apk`. These also
have an entry within `resources.arsc` that maps to them from a resource ID.
* **RAM:** None unless resources are accessed.
* **Start-up**: None unless resources are accessed.
### Other Assets
ICU data, V8 snapshot, etc.
* **RAM:** _Clean Memory_
* **Start-up:** No effect beyond page faults.
Codebase Browser
chromium