alloy: Delete Alloy bootstrap (~M127)

[magreenblatt]

trafficstars

Starting with M125 the CEF Alloy runtime has been split into separate style and bootstrap components. Both Chrome style and Alloy style browsers/windows can now be created while using the Chrome bootstrap. The Alloy bootstrap is considered deprecated and will be removed in approximately M127.

Background

CEF currently supports two bootstraps, the Chrome bootstrap and the Alloy bootstrap. Alloy bootstrap usage has been required up to this point for use cases such as external (native) parent and windowless (off-screen) rendering. Starting with M125 it is now possible to create Alloy style browsers for these use cases while running with the Chrome bootstrap. The final step of this migration process will be the removal of Alloy bootstrap code in approximately M127.

Running with the Alloy bootstrap (CefSettings.chrome_runtime = false) will generate a warning message starting with M125. The message looks like this:

[WARNING:main_runner.cc(272)] Alloy bootstrap is deprecated and will be removed in ~M127. See https://github.com/chromiumembedded/cef/issues/3685

Testing

The CEF Sample Application (cefclient on Windows/MacOS, cefsimple on Linux) is available for download here and supports the Chrome and Alloy bootstraps as specified below. Additional test applications, including CEF unit tests (ceftests), can be built and run using the Standard Distribution.

• Chrome bootstrap is supported but default disabled in cefclient & cefsimple versions 125.0.11 and older. To test the Chrome bootstrap in these versions add the --enable-chrome-runtime command-line flag.
• Chrome bootstrap is default enabled in cefclient & cefsimple versions 125.0.14 and newer. To test the Alloy bootstrap in these versions add the --disable-chrome-runtime command-line flag.

Chrome bootstrap + Chrome style is supported in all recent versions (add --enable-chrome-runtime if required). Modes supported with Chrome bootstrap + Chrome style:

• Views framework: Enabled by default (cefclient & cefsimple)
• External (native) parent: Add --use-native (cefclient only & Windows/Linux only)
• Fully styled Chrome UI window: Add --use-native (cefsimple only)

Chrome bootstrap + Alloy style is supported but default disabled in versions 125.0.8 and newer (add --use-alloy-style to enable, and --enable-chrome-runtime if required). Modes supported with Chrome bootstrap + Alloy style:

• Views framework: Enabled by default with cefclient, add --use-views with cefsimple
• Windowless (off-screen) rendering: Add --off-screen-rendering-enabled (cefclient only)
• External (native) parent: Enabled by default with cefsimple, add --use-native with cefclient

See here for additional testing instructions including various runtime modes and unit test commands.

Migration Route

Windowed applications using Alloy style may wish to use Chrome style as it provides substantially more default functionality (details here). To switch a windowed application from Alloy style to Chrome style simply set CefSettings.chrome_runtime = true before calling CefInitialize.

Migrating an application from the Alloy bootstrap to the Chrome bootstrap while keeping Alloy style is a bit more involved. Here are the steps:

1. Set CefSettings.chrome_runtime = true before calling CefInitialize.
2. Make the following changes depending on your Alloy usage:
   • With external parent: Set CefWindowInfo.runtime_style = CEF_RUNTIME_STYLE_ALLOY before calling CefBrowserHost::CreateBrowser.
   • With windowless rendering: Alloy style is used by default.
   • With the Views framework: Return CEF_RUNTIME_STYLE_ALLOY from CefWindowDelegate::GetWindowRuntimeStyle and CefBrowserViewDelegate::GetBrowserRuntimeStyle.

What's Different

Chrome bootstrap + Alloy style behavior differs from Alloy bootstrap in the following significant ways:

• Supports Chrome error pages by default.
• DevTools popups are Chrome style only (cannot be windowless).
• The Alloy extension API is not supported (will be removed in ~M127). The Chrome extension API is supported with Chrome style browsers/windows only.

Known issues specific to Chrome bootstrap + Alloy style:

• DevTools popups don't load successfully in combination with windowless rendering. Use windowed rendering or remote debugging as a workaround.

Reporting Issues

If you run into any additional issues while migrating your application to the Chrome bootstrap please let us know by posting on the CEF Forum or filing a bug in the CEF issue tracker.

[magreenblatt]

Decide how to handle features that are currently default-disabled with Alloy bootstrap.

• CalculateNativeWinOcclusion should be disabled for browsers with Alloy style windowless rendering or native parent.
• BackForwardCache can be enabled by default with Chrome runtime + Alloy style.
• DocumentPictureInPictureAPI should be disabled for all browsers with Alloy style.

[magreenblatt]

CalculateNativeWinOcclusion should be disabled for browsers with Alloy style windowless rendering or native parent.

We can leave this as the default (enabled) for now, until/unless anyone spots issues related to it. It can also be disabled globally be passing --disable-features=CalculateNativeWinOcclusion on the command-line.

[magreenblatt]

DocumentPictureInPictureAPI should be disabled for all browsers with Alloy style.

Unfortunately document PiP can't be disabled on a per-browser basis. There are two way to handle this currently with Alloy style (in OnBeforePopup when target_disposition == CEF_WOD_NEW_PICTURE_IN_PICTURE):

1. Return true. This will cause document PiP to fail with DOMException: Failed to execute 'requestWindow' on 'DocumentPictureInPicture': Internal error: no window
2. Use default handling (current cefclient implementation). This will cause the document PiP window to open with default Alloy styling.

Document PiP can also be disabled globally be passing --disable-features=DocumentPictureInPictureAPI on the command-line, resulting in ReferenceError: documentPictureInPicture is not defined.

See issue #3448 for reproduction steps.

[magreenblatt]

Verify that Chrome bootstrap supports all CefSettings.

The following CefSettings parameters are not yet implemented for Chrome bootstrap:

• ~~browser_subprocess_path~~ (DONE)
• ~~framework_dir_path~~ (DONE)
• ~~main_bundle_path~~ (DONE)
• persist_user_preferences (will be removed; always enabled with Chrome bootstrap)
• ~~log_file~~ (DONE) (--log-file is already supported)
• ~~log_severity~~ (DONE) (--log-level is already supported)
• ~~log_items~~ (DONE)
• ~~resources_dir_path~~ (DONE)
• ~~locales_dir_path~~ (DONE)
• pack_loading_disabled (will be removed; unsupported)

[magreenblatt]

Also need to add Chrome bootstrap support for CefResourceBundleHandler (by passing CefResourceBundleDelegate to InitSharedInstanceWithLocale here and here). This would also potentially allow us to support pack_loading_disabled, if we disabled resource-related code in those locations and moved it to ChromeMainDelegateCef.

[magreenblatt]

All prep work is now complete (in current master) for the removal of Alloy bootstrap in ~127.

[magreenblatt]

Also posted to cef-announce: https://groups.google.com/g/cef-announce/c/s1WaovAopFo/m/LV5eiNX1BgAJ

[EamonHetherton]

I have found a blocking issue for me in removing the Alloy bootstrap: https://github.com/chromiumembedded/cef/issues/3721

[amaitland]

@magreenblatt Now that the work has been done to remove alloy. Would it be possible to update the issue to explicitly say which version alloy will be removed in?

Thanks!

[magreenblatt]

Would it be possible to update the issue to explicitly say which version alloy will be removed in?

Sure. The changes have landed in current master, so the first impacted release branch will be M128.

[amaitland]

Thank you!

[magreenblatt]

The Architecture Wiki page has been updated for Alloy bootstrap removal.

[JCYang]

• locales_dir_path Hi, in the post 'locales_dir_path' and 'resource_dir_path' are marked as 'DONE', but I've tested the 128.0.6613.18 preview build from https://cef-builds.spotifycdn.com/index.html#linux64 lately, it doesn't work, not yet contained in this build?

more accurately speaking, it is 'resource_dir_path' not working as expected.

[magreenblatt]

more accurately speaking, it is 'resource_dir_path' not working as expected.

See #3749

[ybj1998]

Is windowless rendering still support since M128？

[amaitland]

Is windowless rendering still support since M128？

Yes, with alloy styling.