1. Chromium Embedded Framework Avatar Chromium Embedded Framework
  2. cef
  3. cef

Wiki

Clone wiki

cef / Tutorial

View History

This Wiki page explains how to create a simple application using CEF3.

Note to Editors: Changes made to this Wiki page without prior approval via the CEF Forum or Issue Tracker may be lost or reverted.

Introduction

This tutorial explains how to create a simple application using CEF3. It references the cefsimple example project. For complete CEF3 usage information visit the GeneralUsage Wiki page.

Getting Started

CEF provides a sample project that makes it really easy to get started with CEF development. Simply browse over to the cef-project website and follow the step-by-step instructions. The source files linked from this tutorial are for the current CEF3 master branch and may differ slightly from the versions that are downloaded by cef-project.

Loading a Custom URL

The cefsimple application loads google.com by default but you can change it to load a custom URL instead. The easiest way to load a different URL is via the command-line.

# Load the local file “c:\example\example.html”
cefsimple.exe --url=file://c:/example/example.html

You can also edit the source code in cefsimple/simple_app.cc and recompile the application to load your custom URL by default.

// Load the local file “c:\example\example.html”
…
if (url.empty())
  url = "file://c:/example/example.html";
…

Application Components

All CEF applications have the following primary components:

  1. The CEF dynamic library (libcef.dll on Windows, libcef.so on Linux, “Chromium Embedded Framework.framework” on OS X).
  2. Support files (*.pak and *.bin binary blobs, etc).
  3. Resources (html/js/css for built-in features, strings, etc).
  4. Client executable (cefsimple in this example).

The CEF dynamic library, support files and resources will be the same for every CEF-based application. They are included in the Debug/Release or Resources directory of the binary distribution. See the README.txt file included in the binary distribution for details on which of these files are required and which can be safely left out. See below for a detailed description of the required application layout on each platform.

Architecture in 60 Seconds

The below list summarizes the items of primary importance for this tutorial:

  • CEF uses multiple processes. The main application process is called the “browser” process. Sub-processes will be created for renderers, plugins, GPU, etc.
  • On Windows and Linux the same executable can be used for the main process and sub-processes. On OS X you are required to create a separate executable and app bundle for sub-processes.
  • Most processes in CEF have multiple threads. CEF provides functions and interfaces for posting tasks between these various threads.
  • Some callbacks and functions may only be used in particular processes or on particular threads. Make sure you read the source code comments in the API headers before you begin using a new callback or function for the first time.

Read the GeneralUsage Wiki page for complete discussion of the above points.

Source Code

The cefsimple application initializes CEF and creates a single popup browser window. The application terminates when all browser windows have been closed. Program flow is as follows:

  1. The OS executes the browser process entry point function (main or wWinMain).
  2. The entry point function:
    1. Creates an instance of SimpleApp which handles process-level callbacks.
    2. Initializes CEF and runs the CEF message loop.
  3. After initialization CEF calls SimpleApp::OnContextInitialized(). This method:
    1. Creates the singleton instance of SimpleHandler.
    2. Creates a browser window using CefBrowserHost::CreateBrowser().
  4. All browsers share the SimpleHandler instance which is responsible for customizing browser behavior and handling browser-related callbacks (life span, loading state, title display, etc).
  5. When a browser window is closed SimpleHandler::OnBeforeClose() is called. When all browser windows have closed the OnBeforeClose implementation quits the CEF message loop to exit the application.

Your binary distribution may include newer versions of the below files. However, the general concepts remain unchanged.

Entry Point Function

Execution begins in the browser process entry point function. This function is responsible for initializing CEF and any OS-related objects. For example, it installs X11 error handlers on Linux and allocates the necessary Cocoa objects on OS X. OS X has a separate entry point function for helper processes.

SimpleApp

SimpleApp is responsible for handling process-level callbacks. It exposes some interfaces/methods that are shared by multiple processes and some that are only called in a particular process. The CefBrowserProcessHandler interface, for example, is only called in the browser process. There’s a separate CefRenderProcessHandler interface (not shown in this example) that is only called in the render process. Note that GetBrowserProcessHandler() must return |this| because SimpleApp implements both CefApp and CefBrowserProcessHandler. See the GeneralUsage Wiki page or API header files for additional information on CefApp and related interfaces.

SimpleHandler

SimpleHandler is responsible for handling browser-level callbacks. These callbacks are executed in the browser process. In this example we use the same CefClient instance for all browsers, but your application can use different CefClient instances as appropriate. See the GeneralUsage Wiki page or API header files for additional information on CefClient and related interfaces.

Build Steps

Build steps vary depending on the platform. Explore the CMake files included with the binary distribution for a complete understanding of all required steps. The build steps common to all platforms can generally be summarized as follows:

  1. Compile the libcef_dll_wrapper static library.
  2. Compile the application source code files. Link against the libcef dynamic library and the libcef_dll_wrapper static library.
  3. Copy libraries and resources to the output directory.

Windows Build Steps

  1. Compile the libcef_dll_wrapper static library.
  2. Compile/link cefsimple.exe.
    • Required source code files include: cefsimple_win.cc, simple_app.cc, simple_handler.cc, simple_handler_win.cc.
    • Required link libraries include: comctl32.lib, shlwapi.lib, rcprt4.lib, libcef_dll_wrapper.lib, libcef.lib, cef_sandbox.lib. Note that cef_sandbox.lib (required for sandbox support) is a static library currently built with Visual Studio 2022 and it may not compile with other Visual Studio versions. See comments in cefsimple_win.cc for how to disable sandbox support.
    • Resource file is cefsimple.rc.
    • Manifest files are cefsimple.exe.manifest and compatibility.manifest.
  3. Copy all files from the Resources directory to the output directory.
  4. Copy all files from the Debug/Release directory to the output directory.

The resulting directory structure looks like this for 2526 branch:

Application/
    cefsimple.exe  <= cefsimple application executable
    libcef.dll <= main CEF library
    icudtl.dat <= unicode support data
    libEGL.dll, libGLESv2.dll, ... <= accelerated compositing support libraries
    cef.pak, devtools_resources.pak, ... <= non-localized resources and strings
    natives_blob.bin, snapshot_blob.bin <= V8 initial snapshot
    locales/
        en-US.pak, ... <= locale-specific resources and strings

Linux Build Steps

  1. Compile the libcef_dll_wrapper static library.
  2. Compile/link cefsimple.
    • Required source code files include: cefsimple_linux.cc, simple_app.cc, simple_handler.cc, simple_handler_linux.cc.
    • Required link libraries include: libcef_dll_wrapper.a, libcef.so and dependencies (identified at build time using the “pkg-config” tool).
    • Configure the rpath to find libcef.so in the current directory (“-Wl,-rpath,.”) or use the LD_LIBRARY_PATH environment variable.
  3. Copy all files from the Resources directory to the output directory.
  4. Copy all files from the Debug/Release directory to the output directory.
  5. Set SUID permissions on the chrome-sandbox executable to support the sandbox. See binary distribution build output for the necessary command.

The resulting directory structure looks like this for 2526 branch:

Application/
    cefsimple <= cefsimple application executable
    chrome-sandbox <= sandbox support binary
    libcef.so <= main CEF library
    icudtl.dat <= unicode support data
    cef.pak, devtools_resources.pak, ... <= non-localized resources and strings
    natives_blob.bin, snapshot_blob.bin <= V8 initial snapshot
    locales/
        en-US.pak, ... <= locale-specific resources and strings
    files/
        binding.html, ... <= cefclient application resources

Mac OS X Build Steps

  1. Compile the libcef_dll_wrapper static library.
  2. Compile/link/package the “cefsimple Helper” app.
    • Required source code files include: process_helper_mac.cc.
    • Required link frameworks include: AppKit.framework.
    • App bundle configuration is provided via “cefsimple/mac/helper-Info.plist”.
    • Load the CEF Framework as described here.
  3. Compile/link/package the “cefsimple” app.
    • Required source code files include: cefsimple_mac.mm, simple_app.cc, simple_handler.cc, simple_handler_mac.mm.
    • Required link frameworks include: AppKit.framework.
    • App bundle configuration is provided via “cefsimple/mac/Info.plist”.
    • Load the CEF Framework as described here.
  4. Create a Contents/Frameworks directory in the cefsimple.app bundle. Copy the following files to that directory: “cefsimple Helper.app”, “Chromium Embedded Framework.framework”.

The resulting directory structure looks like this for 2526 branch:

cefsimple.app/
    Contents/
        Frameworks/
            Chromium Embedded Framework.framework/
                Chromium Embedded Framework <= main application library
                Resources/
                    cef.pak, devtools_resources.pak, ... <= non-localized resources and strings
                    icudtl.dat <= unicode support data
                    natives_blob.bin, snapshot_blob.bin <= V8 initial snapshot
                    en.lproj/, ... <= locale-specific resources and strings
            cefsimple Helper.app/
                Contents/
                    Info.plist
                    MacOS/
                        cefsimple Helper <= helper executable
                    Pkginfo
        Info.plist
        MacOS/
            cefsimple <= cefsimple application executable
        Pkginfo
        Resources/
            cefsimple.icns, ... <= cefsimple application resources

Updated