CEF Installer Library Documentation

The C++ Rewriter Tool is a clang-based AST rewriter designed for C++20 modernization. It performs type-aware code transformations that go beyond simple regex, such as converting map.find(x) != map.end() to map.contains(x).

It is distributed as a self-contained package including:

• bin/cpp_rewriter: The core rewriter tool.
• lib/clang/<version>/: Bundled clang headers to ensure compatibility without requiring a matching system clang.
• scripts/: Python wrapper scripts (run_rewriter.py, apply_edits.py, process_edits.py) for executing and applying transformations.

The cef_cpp_rewriter is a clang AST-based tool designed to automate C++20 modernization for CEF code. It performs several specific transformations to modernize the codebase.

Supported transformations:

• .contains() for associative containers
• Structured bindings for range-for loops
• Iterator loops to range-for
• DISALLOW_COPY_AND_ASSIGN replacement

For a complete list of transformations, command-line flags, and examples, refer to TRANSFORMS.md.

The macOS distribution of CEF contains the following key components:

• include: All required CEF header files.
• libcef_dll: Source code for the libcef_dll_wrapper static library. All applications using the CEF C++ API must link against this library.
• Release: Contains Chromium Embedded Framework.framework and other components required to run the release version of CEF-based applications.
• cmake: CMake configuration files shared by all targets.
• bazel: Bazel configuration files shared by all targets.

A standard CEF binary distribution contains the following key components:

• include/: CEF header files (cef_*.h for C++ and capi/ for C API).
• libcef_dll/: C++ wrapper implementation.
• Release/ or Debug/: Build artifacts containing the main library (libcef.so/.dylib/.dll), binary data files (*.bin), and other required files.
• Resources/: Resource files (e.g., *.pak).
• tests/: Example applications including cefsimple (C++), cefsimple_capi (C), cefclient (comprehensive), and ceftests (unit tests).

When working with the libcef codebase (the implementation layer between Chromium and the CEF public API), common tasks include:

• Adding new APIs: Exposing new functionality to CEF clients.
• Implementing handlers: Creating implementations for WebContentsDelegate and other Chromium delegates.
• Fixing bugs: Debugging and fixing issues within the CEF implementation layer.
• Updating for Chromium changes: Adapting CEF to accommodate upstream Chromium API changes.

A basic CEF application using the Views framework consists of several key components:

• SimpleApp (Application-level handler): Created when CEF initializes. It manages the browser and window creation using the Views framework.
• SimpleHandler (Browser-level event handler): Manages browser lifecycle events (e.g., OnBeforeClose). It typically implements a singleton pattern to be accessible by platform entry points.
• Views Framework Delegates:
  • SimpleWindowDelegate: Controls window properties like size, close behavior, and runtime style.
  • SimpleBrowserViewDelegate: Specifies the browser's runtime style (e.g., Alloy).
• Platform Entry Point Methods: Methods like GetInstance(), CloseAllBrowsers(), IsClosing(), and ShowMainWindow() are used by platform-specific code (like macOS dock interactions) to communicate with the application instance.

CEF3 is the current recommended version of CEF. It uses a multi-process architecture similar to the Chromium browser. It supports two main runtimes:

1. Alloy Runtime: Based on the Chromium 'content' layer. Note that starting with M128 (mid-2024), the Alloy bootstrap has been removed. Alloy style is now supported using the Chrome runtime bootstrap.
2. Chrome Runtime: Based on the 'chrome' layer. It includes advanced features like extensions, gamepad, webhid, and webmidi, along with standard Chrome UI toolbars and dialogs. The Chrome runtime requires the use of the Views framework and does not support off-screen rendering.

For detailed instructions on process and threading models, refer to the General Usage guide.

The CEF Installer uses a security model based on durable registration identity and integrity-valid launch evidence. It does not infer ownership from executable paths or ACLs.

Key Security Principles:

• Registration: Only source-derived per-user-default and custom install_path stores are eligible. HKLM and Program Files roles are considered provisioning-owned and are ineligible for user-level registration.
• Fail-Closed Design: Missing, malformed, non-canonical, mismatched, zero, or future-dated evidence results in a 'fail closed' state (unknown/protected).
• Integrity: Cleanup processes use exact, same-file-object comparisons to prevent symlink or junction redirection attacks during deletion.

CEF utilizes a multi-process architecture:

• Browser process: Main process handling UI, navigation, and coordination.
• Renderer process: Handles web content (isolated/sandboxed).
• GPU process: Handles graphics acceleration.
• Other processes: Network service, audio service, etc.

Threading Model:

• TID_UI: Browser process main thread.
• TID_IO: Network operations.
• TID_RENDERER: Renderer process main thread (JavaScript execution).

Thread Safety: Use assertions to ensure code runs on the correct thread:

• CEF_REQUIRE_UI_THREAD()
• CEF_REQUIRE_RENDERER_THREAD()

To post tasks across threads, use CefPostTask:

#include "include/base/cef_callback.h"
#include "include/wrapper/cef_closure_task.h"

CefPostTask(TID_UI, base::BindOnce(&MyClass::MyMethod, this, arg));

CEF/Chromium builds are tied to specific host architectures. You must run the tools binaries on the supported host OS/architecture, even if your target application is for a different architecture.

Supported host architectures:

• Linux: x86-64 (Intel/AMD)
• Windows: x86-64 (Intel/AMD)
• MacOS: ARM64 (Apple Silicon)

Example: To create files for a MacOS 64-bit (Intel) application, you must use the MacOS 64-bit (Intel) tools distribution running on a MacOS ARM64 (Apple Silicon) host system.

The macOS distribution contains two versions of the libcef_sandbox.dylib library located in the following directories:

• Debug: Contains the Debug build of libcef_sandbox.dylib.
• Release: Contains the Release build of libcef_sandbox.dylib.