Blink‎ > ‎

Runtime Enabled Features

Overview

Runtime flags enable Blink developers the ability to control access Chromium users have to new features they implement. Features that are hidden behind a runtime flag are known as Runtime Enabled Features. It is a requirement of the Blink Launch Process to implement new features behind a runtime flag until an Intent To Ship has been approved.



Adding A Runtime Enabled Feature

Runtime Enabled Features are defined in RuntimeEnabledFeatures.in in alphabetical order. Add your feature's flag to this file and the rest will be generated for you automatically.

Example:

AmazingNewFeature status=experimental

The status of the feature controls when it will be enabled in the Blink engine.

Status valueEnabled during layout
content_shell tests [1]
Enabled through the
about:flags page [2]
Enabled in stable release
 <missing>NoNoNo
 testYesNoNo
 experimentalYesYesNo
 stableYesYesYes

[1] content_shell will not enable experimental/test features by default, the --dump-render-tree flag enables this behaviour.
[2] Navigate to about:flags in the URL bar and turn on "Enable experimental web platform features" (formerly, "Enable experimental WebKit features")
     or run Chromium with --enable-experimental-web-platform-features (formerly, --enable-experimental-webkit-features)
     Works in all Chromium channels: canary, dev, beta, and stable.


Runtime Enabled CSS Properties

If your feature is adding new CSS Properties you will need to modify Source/core/css/RuntimeCSSEnabled.cpp and add it to the setPropertySwitchesFromRuntimeFeatures function.




Using A Runtime Enabled Feature

C++ Source Code
Add this include:
#include "RuntimeEnabledFeatures.h"

This will provide following static methods to check/set whether your feature is enabled:
bool RuntimeEnabledFeatures::amazingNewFeatureEnabled();
void RuntimeEnabledFeatures::setAmazingNewFeatureEnabled(bool isEnabled);

Note: methodNames are in lowerCamelCase, while FeatureNames are in UpperCamelCase. This is handled automatically in code generators, and works even if the feature's flag name begins with an acronym such as "CSS", "IME", or "HTML".
For example "CSSMagicFeature" becomes RuntimeEnabledFeatures::cssMagicFeatureEnabled() and RuntimeEnabledFeatures::setCSSMagicFeatureEnabled(bool).


IDL files
Use the Blink extended attribute [RuntimeEnabled] as in [RuntimeEnabled=AmazingNewFeature] in your IDL definition.
Note: FeatureNames are in UpperCamelCase; please use this case in IDL files.

You can guard the entire interface, as in this example:
[
    RuntimeEnabled=AmazingNewFeature  // Guard the entire interface.
] interface AmazingNewObject {
    attribute DOMString amazingNewAttribute;
    void amazingNewMethod();
}

Alternatively, you can guard individual definition members:

interface AmazingNewObject {
    // Guarded attribute.
    [RuntimeEnabled=AmazingNewFeature] attribute DOMString amazingNewAttribute;
    // Guarded method.
    [RuntimeEnabled=AmazingNewFeature] void amazingNewMethod();
}

Warning: You will not be able to change the enabled state of these at runtime as the V8 object templates definitions are created during start up and will not be updated during runtime.


Layout Tests (JavaScript)
Test whether a feature is enabled using:
internals.runtimeFlags.amazingNewFeatureEnabled

This attribute is read only and cannot be changed.

Note: The internals JavaScript API is only available in ContentShell for use by Layout Tests and does not appear in released versions of Chromium.




Generated Files
<compilation directory>/gen/webkit/RuntimeEnabledFeatures.h
<compilation directory>/gen/webkit/RuntimeEnabledFeatures.cpp

<compilation directory>/gen/webkit/InternalRuntimeFlags.idl
<compilation directory>/gen/webkit/InternalRuntimeFlags.h

Source/bindings/scripts/CodeGeneratorV8.pm uses the generated InternalRuntimeFlags.idl to generate:
<compilation directory>/gen/webcore/bindings/V8InternalRuntimeFlags.cpp


Announcement

Comments