AW docs: update Feature Flag technical docs
No change to logic. No change to policy. This updates the commandline-flags.md technical documentation with two changes in mind: * Update the terminology for Feature Flags. The `base::Feature` syntax was recently swapped out for a C++ macro. In an attempt to be more future-proof, let's refer to this concept as a "Feature Flag" and let the syntax be an implementation detail. * Clarify the difference between Commandline Switches vs. Feature Flags. * Includes copy-pasteable shell commands for toggling Feature Flags. Fixed: 1378392 Test: Upload to gerrit > open file > click "preview" Change-Id: I96d02b431acec7735687ddc55b460ef73acfab44 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3980294 Commit-Queue: Nate Fischer <ntfschr@chromium.org> Reviewed-by: Susanne Westphal <swestphal@chromium.org> Auto-Submit: Nate Fischer <ntfschr@chromium.org> Cr-Commit-Position: refs/heads/main@{#1065036}
This commit is contained in:

committed by
Chromium LUCI CQ

parent
8d2f6957ca
commit
1dafec9464
@ -31,21 +31,39 @@ If the above outputs "user," then you have two options:
|
||||
* Reflash your device or create a debuggable emulator (see [device
|
||||
setup](device-setup.md))
|
||||
|
||||
## Applying flags
|
||||
## Overview
|
||||
|
||||
WebView (and Chromium in general) has two different types of "commandline
|
||||
flags:"
|
||||
|
||||
* **Commandline Switches** enable debugging functionality. These look like
|
||||
`--name-of-switch`.
|
||||
* **Feature Flags** configure WebView to enable or disable an in-development
|
||||
project or enhancement. These look like `NameOfFeature`.
|
||||
|
||||
Before applying commandline flags, you should understand which specific flags
|
||||
you want to flip and whether each is a Commandline Switch or Feature Flag.
|
||||
Then follow the steps below.
|
||||
|
||||
## Applying Commandline Switches {#commandline-switches}
|
||||
|
||||
<!-- Note: keep this language consistent with the section below. Search for
|
||||
"kill and restart" -->
|
||||
WebView reads flags from a specific file on the device as part of the startup
|
||||
sequence. Therefore, it's important to always **kill the WebView-based app**
|
||||
you're examining after modifying commandline flags, to ensure the flags are
|
||||
picked up during the next app restart.
|
||||
sequence. Therefore, it's important to always **kill and restart the
|
||||
WebView-based app** you're examining after modifying commandline flags to ensure
|
||||
the flags are picked up.
|
||||
|
||||
WebView always looks for the same file on the device
|
||||
(`/data/local/tmp/webview-command-line`), regardless of which package is the
|
||||
[the WebView provider](prerelease.md).
|
||||
|
||||
### Python script
|
||||
### Python script (recommended)
|
||||
|
||||
The simplest way to set WebView flags is with the dedicated python script. This
|
||||
works regardless of which package is the WebView provider:
|
||||
works regardless of which package is the WebView provider. **Note:** this script
|
||||
will overwrite any Commandline Switches or Feature Flags which had previously
|
||||
been applied.
|
||||
|
||||
```sh
|
||||
# Overwrite flags (supports multiple)
|
||||
@ -72,11 +90,11 @@ out/Default/bin/system_webview_apk argv
|
||||
```
|
||||
|
||||
*** note
|
||||
**Note:** be careful if using a `monochrome_*` target, as the Generated Wrapper
|
||||
Script writes to Chrome browser's flags file, and WebView **will not pick up
|
||||
these flags**. If using Monochrome, you can set flags with the
|
||||
`system_webview_*` Generated Wrapper Scripts, or use one of the other methods
|
||||
in this doc.
|
||||
**Note:** this method is only supported for `system_webview_*` and
|
||||
`trichrome_webview_*` targets. Be careful when using a `monochrome_*` target, as
|
||||
this will write to Chrome browser's flags file, and WebView **will not pick up
|
||||
these flags**. If using Monochrome, you should instead use the python script
|
||||
mentioned above.
|
||||
***
|
||||
|
||||
### Manual
|
||||
@ -104,32 +122,57 @@ device logs with:
|
||||
adb logcat | grep -iE 'Active field trial|WebViewCommandLine'
|
||||
```
|
||||
|
||||
## Applying Features with flags
|
||||
## Applying Feature Flags
|
||||
|
||||
[`base::Feature`s](/base/feature_list.h) (or, "Features") are Chromium's
|
||||
mechanism for toggling off-by-default code paths. While debugging flags are also
|
||||
off-by-default, Features typically guard soon-to-launch product enhancements
|
||||
until they're tested enough for field trials or public launch, at which point
|
||||
the Feature is removed and the legacy code path is no longer supported and
|
||||
removed from the codebase. On the other hand, debugging flags don't "launch," as
|
||||
they're typically only helpful for debugging issues.
|
||||
[Feature Flags](/base/feature_list.h) (also stylized as `base::Feature` or
|
||||
`BASE_FEATURE`) are Chromium's mechanism for toggling off-by-default code paths.
|
||||
While debugging flags are also off-by-default, Feature Flags typically guard
|
||||
soon-to-launch product enhancements until they're tested enough for field trials
|
||||
or public launch, at which point the Feature Flag is removed and the legacy code
|
||||
path is no longer supported and removed from the codebase. On the other hand,
|
||||
debugging flags don't "launch," as they're typically only helpful for debugging
|
||||
issues.
|
||||
|
||||
WebView supports the same syntax for toggling Features as the rest of chromium:
|
||||
`--enable-features=feature1,feature2` and
|
||||
WebView supports the same syntax for toggling Feature Flags as the rest of
|
||||
chromium: `--enable-features=feature1,feature2` and
|
||||
`--disable-features=feature3,feature4`. You can apply `--enable-features` and
|
||||
`--disable-features` like any other flags, per the steps above. Please consult
|
||||
[`base/feature_list.h`](/base/feature_list.h) for details.
|
||||
[`base/feature_list.h`](/base/feature_list.h) for details. Examples of toggling
|
||||
Feature Flags:
|
||||
|
||||
## Finding Features and flags
|
||||
```sh
|
||||
# Enable a single Feature Flag:
|
||||
build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature
|
||||
|
||||
WebView supports toggling any flags/Features supported in any layer we
|
||||
depend on (ex. content). For more details on Chromium's layer architecture, see
|
||||
[this diagram](https://www.chromium.org/developers/content-module) (replace
|
||||
"chrome" with "android\_webview"). Although we support toggling these flags, not
|
||||
all flags will have an effect when toggled, nor do we guarantee WebView
|
||||
functions correctly when the flag is toggled.
|
||||
# Enable multiple Feature Flags:
|
||||
build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature,WebViewBrotliSupport
|
||||
|
||||
Some interesting flags and Features:
|
||||
# Enable and disable Feature Flags:
|
||||
build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature --disable-features=WebViewBrotliSupport
|
||||
|
||||
# Use Commandline Switches and Feature Flags at the same time:
|
||||
build/android/adb_system_webview_command_line --highlight-all-webviews --enable-features=WebViewTestFeature
|
||||
```
|
||||
|
||||
As with [Commandline Switches](#commandline-switches), we support multiple tools
|
||||
for toggling Feature Flags (Python script, Generated Wrapper Script, manual).
|
||||
|
||||
<!-- Note: keep this language consistent with the section above. Search for
|
||||
"kill and restart" -->
|
||||
As before, it's important to **kill and restart the WebView-based app** you're
|
||||
examining after modifying flags to ensure the flags are picked up.
|
||||
|
||||
## Finding Feature Flags and Commandline Switches
|
||||
|
||||
WebView supports toggling any Commandline Switches or Feature Flags supported in
|
||||
any layer we depend on (//base, //content, etc.). For more details on Chromium's
|
||||
layer architecture, see [this
|
||||
diagram](https://www.chromium.org/developers/content-module) (replace "chrome"
|
||||
with "android\_webview"). Although we support toggling these flags, not all
|
||||
flags will have an effect when toggled, nor do we guarantee WebView functions
|
||||
correctly when the flag is toggled.
|
||||
|
||||
Some interesting Commandline Switches:
|
||||
|
||||
* `--highlight-all-webviews`: highlight the entire contents of all WebViews, to
|
||||
quickly identify which app content is rendered by a WebView vs. native Views.
|
||||
@ -139,17 +182,17 @@ Some interesting flags and Features:
|
||||
override app opt-out)
|
||||
* `--finch-seed-expiration-age=0 --finch-seed-min-update-period=0 --finch-seed-min-download-period=0 --finch-seed-ignore-pending-download`: always request a new finch seed when an app starts
|
||||
|
||||
WebView also defines its own flags and Features:
|
||||
WebView also defines its own Commandline Switches and Feature Flags:
|
||||
|
||||
* C++ switches are defined in
|
||||
* C++ Commandline Switches are defined in
|
||||
[`aw_switches.cc`](/android_webview/common/aw_switches.cc). We use
|
||||
[`java_cpp_strings`](/docs/android_accessing_cpp_switches_in_java.md) to
|
||||
automatically generate Java switch constants from the C++ switches (see
|
||||
[`AwSwitches.java`](https://source.chromium.org/chromium/chromium/src/+/main:out/android-Debug/gen/android_webview/common_java/generated_java/input_srcjars/org/chromium/android_webview/common/AwSwitches.java)).
|
||||
* C++ `base::Features` are defined in
|
||||
* C++ Feature Flags are defined in
|
||||
[`aw_features.cc`](/android_webview/common/aw_features.cc). We use
|
||||
[`java_cpp_features`](/docs/android_accessing_cpp_features_in_java.md) to
|
||||
automatically generate Java constants from the C++ Features (see
|
||||
automatically generate Java constants from the C++ Feature Flags (see
|
||||
[`AwFeatures.java`](https://source.chromium.org/chromium/chromium/src/+/main:out/android-Debug/gen/android_webview/common_java/generated_java/input_srcjars/org/chromium/android_webview/common/AwFeatures.java)).
|
||||
|
||||
## Implementation
|
||||
|
Reference in New Issue
Block a user