chromium/src
0
Fork 0
Code Activity

AW docs: update Feature Flag technical docs

Browse Source 
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:
Nate Fischer
2022-10-28 21:12:22 +00:00
committed by Chromium LUCI CQ
parent 8d2f6957ca
commit 1dafec9464
1 changed files with 77 additions and 34 deletions

111
android_webview/docs/commandline-flags.md

@ -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