Initialization of Blink runtime features in content layer

This document outlines how to initialize your Blink runtime features in the Chromium content layer, more specifically incontent/child/runtime_features.cc. To learn more on how to set up features in blink, seeRuntime Enabled Features.

Step 1: Do you need a custom Blink feature enabler function?

If you simply need to enable/disable the Blink feature you can simply useWebRuntimeFeatures::EnableFeatureFromString().

However, if there are side effects (e.g. you need to disable other features if this feature is also disabled), you should declare a custom enabler function in

• third_party/blink/public/platform/web_runtime_features.h
• third_party/blink/renderer/platform/exported/web_runtime_features.cc

Step 2: Determine how your feature is initialized.

1) Depends on OS-specific Macros:

Add your code for controlling the Blink feature inSetRuntimeFeatureDefaultsForPlatform() using the appropriate OS macros.

2) Depends on the status of a base::Feature:

Add your code to the functionSetRuntimeFeaturesFromChromiumFeatures().

If your Blink feature has a custom enabler function, add a new entry toblinkFeatureToBaseFeatureMapping. For example, a new entry like this:

{wf::EnableNewFeatureX, features::kNewFeatureX, kDefault},

will callwf::EnableNewFeatureX to enable it only iffeatures::kNewFeatureX is enabled, or to set it to the same status asfeatures::kNewFeatureX if its default status is overridden by any field trial or command line switch.

If your Blink feature does not have a custom enabler function, you need to add the entry toruntimeFeatureNameToChromiumFeatureMapping. For example, a new entry like this:

{"NewFeatureY", features::kNewFeatureY, kDefault},

will callwf::EnableFeatureFromString with your feature name instead ofwf::EnableNewFeatureX in the same cases as above.

The following table summarizes the relationship between the default status of the Chromium feature and the status of the blink feature, whenkDefault is specified, ifnot overridden by field trial or command line switches (horizontal headers: blink feature status; vertical headers: chromium feature default status):

[1]:base::FeatureList::IsEnabled(features::kNewFeatureX) is still false. These combinations are suitable for features there are fully implemented at blink side. Otherwise normally the blink feature should not have a status so that the Chromium feature can fully control the feature.

[2]: This combination is counter-intuitive and should be avoided.

Field trial and command line switches can always override the Chromium feature status and the blink feature status.

BesideskDefault, there are also other options for the relationship between the Chromium feature and the blink feature. These other options should only be used in rare cases when the default relationship doesn't work.

For more detailed explanation on the options you have, read the comment in enumRuntimeFeatureEnableOptions.

3) Set by a command line switch to enable or disable:

Add your code to the functionSetRuntimeFeaturesFromCommandLine().

If your Blink feature has a custom enabler function, add a new entry toswitchToFeatureMapping. For example, a new entry like this:

{wrf::EnableNewFeatureX, switches::kNewFeatureX, false},

will callwf::EnableNewFeatureX to disable it only if thatswitches::kNewFeatureX exists on the command line.

4) Combination of the previous options or not covered:

For example, you Blink feature could be controlled by both a base::Feature and a command line switch. In this case, your custom logic should live here inSetCustomizedRuntimeFeaturesFromCombinedArgs().