android_webview/docs/custom_orderfile_pgo.md
[TOC]
This document provides instructions for AOSP system integrators on how to generate and apply custom Orderfile and Profile-Guided Optimization (PGO) profiles for WebView builds.
[!NOTE] The tools described in this document do not support x86 or x86-64 architectures. You will need to use an ARM or ARM64 environment (such as a physical device) rather than an x86 emulator.
An orderfile is a list of symbols that defines a specific ordering of functions. A static linker, such as LLD, can follow this ordering when generating a binary to optimize performance. Reordering code improves startup and page load performance by fetching machine code into memory more efficiently. The Orderfile can be generated for both 32-bit (arm) and 64-bit (arm64) architectures.
PGO is a compiler optimization technique that uses profile data collected from representative runs of an application to make better optimization decisions (e.g., inlining, branch prediction).
On Android, PGO is currently only applied to the 64-bit WebView library. The 32-bit library uses AutoFDO (AFDO), which is not covered in this document.
For more general information, see the documentation for Orderfiles and PGO.
To generate a custom PGO profile, follow these steps:
.gclient configurationEnsure that your .gclient file includes the following custom variables:
'custom_vars': {
'checkout_pgo_profiles': True,
'checkout_telemetry_dependencies': True,
},
Run gclient sync to fetch the necessary tools.
Create a build directory (e.g., out/pgo-generate) and configure the GN
arguments for the instrumentation phase.
chrome_pgo_phase = 1
clang_use_default_sample_profile = false
debuggable_apks = false
is_official_build = true
symbol_level = 1
target_cpu = "arm64"
target_os = "android"
v8_is_on_release_branch = true
Build the generation target and run the script to collect profile data.
autoninja -C out/pgo-generate/ tools/pgo:generate_profile_android_webview_64
cd out/pgo-generate/
bin/run_generate_profile_android_webview_64 -vv
This script will run the profiling scenarios on a connected Android device and produce the profile data.
The generated PGO profile will be located at out/pgo-generate/profile.profdata.
The default PGO generation pipeline uses specific scenarios that require an internal checkout. Non-Googler readers should expect to need to perform modifications to the workload or exercise different user journeys. To customize the workload, you should inspect the following script:
Modifying this script allows you to change the scenarios being exercised.
Generating a custom orderfile is useful if you want to optimize for specific use cases.
[!IMPORTANT] Orderfile and PGO Coupling: For the best results on 64-bit builds, you should generate the PGO profile first, and then generate the Orderfile while the custom PGO profile is applied. See the PGO documentation for more context.
.gclient configurationEnsure that your .gclient file includes the following custom variables:
'custom_vars': {
'checkout_pgo_profiles': True,
'checkout_telemetry_dependencies': True,
},
Run gclient sync to fetch the necessary tools.
Create a build directory (e.g., out/orderfile-generate) and configure the
GN arguments. Use the following arguments as a baseline, setting
target_cpu to "arm64" or "arm" depending on your target architecture.
If you generated a custom PGO profile for an arm64 build, you should
apply it here by setting pgo_override_filename to your generated profile
file name after copying it to the appropriate directory (see
Applying PGO).
debuggable_apks = false
enable_proguard_obfuscation = false
is_chrome_branded = false
is_official_build = true
symbol_level = 1
target_cpu = "arm64" # or "arm"
target_os = "android"
use_order_profiling = true
# Optional (arm64 only): Name of your custom PGO profile
# pgo_override_filename = "my_profile.profdata"
Build the generation target using autoninja.
autoninja -C out/orderfile-generate/ \
tools/cygprofile:generate_orderfile_android_webview_64
autoninja -C out/orderfile-generate/ \
tools/cygprofile:generate_orderfile_android_webview
Run the generated script to execute the profiling scenarios and generate the
orderfile. You will need an Android device connected via adb.
cd out/orderfile-generate && bin/run_generate_orderfile_android_webview_64
cd out/orderfile-generate && bin/run_generate_orderfile_android_webview
This script installs the instrumented WebView on your device, sets it as the active provider, exercises the defined user journeys, collects the profiles, and generates the final orderfile.
The generated orderfile will be located in the
out/orderfile-generate/orderfiles/orderfile.arm64.out for arm64 and in
out/orderfile-generate/orderfiles/orderfile.arm.out for arm.
The default orderfile generation pipeline uses specific scenarios that require an internal checkout. Non-Googler readers should expect to need to perform modifications to the workload or exercise different user journeys. To customize the workload, you should inspect the following script and surrounding utility files:
For the exact logic of generating the WebView profile, you can also refer to:
Modifying these scripts allows you to tailor the generation process to match the specific usage patterns required for your system integration.
Once you have generated your custom profiles, you can apply them to an official WebView build. Follow the general instructions in the WebView for AOSP system integrators guide, and add the following GN arguments:
To apply the generated PGO profile to an official build:
my_profile.profdata) into the
//chrome/build/pgo_profiles/ directory.pgo_override_filename GN argument in your official build
configuration to the file name:pgo_override_filename = "my_profile.profdata"
Add the webview_orderfile_path argument to override the orderfile for
both the 32-bit and 64-bit libraries:
webview_orderfile_path = "//path/to/your/custom_orderfile.out"
You can combine both arguments in your official build configuration for maximum optimization on the 64-bit library.