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 in content/child/runtime_features.cc. To learn more on how to set up features in blink, see Runtime 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 use WebRuntimeFeatures::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

Step 2: Determine how your feature is initialized.

1) Depends on OS-specific Macros:

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

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

Add your code to the function SetRuntimeFeaturesFromChromiumFeatures().

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

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

will call wf::EnableNewFeatureX to enable it only if features::kNewFeatureX is enabled, or to set it to the same status as features::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 to runtimeFeatureNameToChromiumFeatureMapping. For example, a new entry like this:

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

will call wf::EnableFeatureFromString with your feature name instead of wf::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, when kDefault is specified, if not overridden by field trial or command line switches (horizontal headers: blink feature status; vertical headers: chromium feature default status):

	No status	`status:"test"`	`status:"experimental"`	`status:"stable"`
`FEATURE_DISABLED_BY_DEFAULT`	Disabled everywhere	Blink feature is enabled for tests, or everywhere with `--enable-blink-test-features` [1]	Blink feature is enabled for tests, or everywhere with `--enable-experimental-web-platform-features` [1]	Blink feature is enabled everywhere [2]
`FEATURE_ENABLED_BY_DEFAULT`	Enabled everywhere	Enabled everywhere	Enabled everywhere	Enabled everywhere

[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 controll 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.

Besides kDefault, 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 enum RuntimeFeatureEnableOptions.

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

Add your code to the function SetRuntimeFeaturesFromCommandLine().

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

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

will call wf::EnableNewFeatureX to disable it only if that switches::kNewFeatureX exists on the command line.

4) Controlled by parameters from a field trial:

Add your code to the function SetRuntimeFeaturesFromFieldTrialParams().

5) 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 in SetCustomizedRuntimeFeaturesFromCombinedArgs().