Skip to content

CEF Build Instructions for macOS

Jump to bottom
Patrick Heyer edited this page Feb 19, 2024 · 1 revision

Building the Chromium Embedded Framework (CEF) on macOS requires selecting a version that is recent enough for a given host operating system, Xcode version, and platform SDK:

macOS Version Xcode version Minimum Compatible CEF Version
macOS 14.0 Xcode 15.0 119 (Branch 6045)
macOS 13.3 Xcode 14.3 115 (Branch 5790)
macOS 13.0 Xcode 14.0 109 (Branch 5414)
macOS 12.3 Xcode 13.3 102 (Branch 5005)

Attempting to build an unsupported combination will lead to build errors as the underlying build scripts will not be compatible with the compiler, linker, or Python version shipped with Xcode.

As of 2024, the minimum suggested CEF Version is 119 (Branch 6045) to enable compilation on macOS 14 host machines.

Quick Start

  1. Create a build directory

  2. Download the automate-git.py script into the created build directory

  3. Set environment variables:

    • export GN_DEFINES="is_official_build=true cc_wrapper=ccache is_debug=false symbol_level=0"
    • export CEF_ARCHIVE_FORMAT=tar.bz2
    • When building for Intel-based Macs on an Apple Silicon-based Mac, set export CEF_ENABLE_AMD64=1
    • When building for Apple Silicon-based Macs on an Intel-based Mac, set export CEF_ENABLE_ARM64=1

  4. Run automate-git.py to build CEF:

    • For Apple Silicon-based Macs run python3 automate-git.py --download-dir=${PWD}/chromium_git --arm64-build --no-debug-build --minimal-distrib-only --branch=<BRANCH> --with-pgo-profiles --force-clean
    • For Intel-based Macs run python3 automate-git.py --download-dir=${PWD}/chromium_git --x64-build --no-debug-build --minimal-distrib-only --branch=<BRANCH> --with-pgo-profiles --force-clean

  5. Wait 😴

  6. Enter chromium_git/chromium/src/cef/binary_distrib/cef_binary_<VERSION>-<BRANCH>-<COMMIT>-<CHROMIUM_VERSION>_macos<PLATFORM>_minimal

  7. Configure the CEF Wrapper build directory:

    • For Apple Silicon-based Macs run cmake -S . -B build -G Xcode -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 -DUSE_SANDBOX=OFF -DPROJECT_ARCH=arm64
    • For Intel-based Macs run cmake -S . -B build -G Xcode -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 -DUSE_SANDBOX=OFF -DPROJECT_ARCH=x86_64

  8. Build the CEF Wrapper by running cmake --build build --config Debug and cmake --build build --config Release

  9. Remove any files and directories inside the build directory except for the Debug and Release directories inside the libcef_dll_wrapper directory

  10. Create the distributable archive by running tar -cvJf cef_binary_<BRANCH>_macos_arm64.tar.xz for Apple Silicon-based Macs or tar -cvJf cef_binary_<BRANCH>_macos_x86_64.tar.xz for Intel-based Macs

  11. Generate the checksum for the generated archive by running shasum -a 256 <ARCHIVE_FILENAME>

Detailed Build Steps

Preparation

  1. Ensure that a compatible Xcode version is installed
  2. Open a Terminal prompt
  3. Check that an available Xcode installation is configured in the Terminal environment via xcode-select -p - by default it should show a path like /Applications/Xcode.app/Contents/Developer
  4. Check that a valid python3 interpreter is available in the Terminal environment via which python3 - by default it should show a path like /usr/bin/python3
  5. Create a new directory for the CEF build
  6. Download the automate-git.py script from the CEF source tree and place it in the created directory

Building

The CEF build script can be controlled by a set of environment variables and command line arguments passed to the automate-git.py script:

  • The GN_DEFINES environment variable contains options used by Chromium's build system - CEF will set sane defaults depending on command line arguments and specified build target. Some customization is possible and will be used in the build steps below.
  • The CEF_ARCHIVE_FORMAT environment variable specifies the format used by the script to archive the final build package
  • The CEF_ENABLE_AMD64 environment variable needs to be specified when building an x86_64 (Intel CPU) version of CEF on an Apple Silicon-based host
  • The CEF_ENABLE_ARM64 environment variable needs to be specified when building an arm64 (Apple Silicon CPU) version of CEF on an Intel-based host

  1. Enter the created build directory

  2. Set the GN_DEFINES environment variable, e.g. export GN_DEFINES=is_official_build=true

    2.1. The build time for CEF can be sped up by specifying additional options to GN_DEFINES:

    • Setting symbol_level=0 will disable the generation of symbols entirely
    • Setting blink_symbol_level=0 and v8_symbol_level=0 will alternatively only disable the generation of symbols for the Blink and V8 engines respectively
    • If ccache is installed, re-builds of CEF can be accelerated by adding cc_wrapper=ccache

    2.2. To enable support for proprietary codecs, ffmpeg_branding=Chrome and proprietary_codecs=true need to be set

The automate-git.py script will merge these values and its own defaults to a full set of build options, e.g.:

alternate_cdm_storage_id_key="<HASH_VALUE>"
cc_wrapper="ccache"
clang_use_chrome_plugins=false
disable_fieldtrial_testing_config=true
enable_background_mode=false
enable_backup_ref_ptr_support=false
enable_basic_printing=true
enable_cdm_host_verification=true
enable_cdm_storage_id=true
enable_downgrade_processing=false
enable_nacl=false
enable_print_preview=true
enable_resource_allowlist_generation=false
enable_rlz=true
enable_widevine=true
forbid_non_component_debug_builds=false
is_component_build=false
is_debug=false
is_official_build=true
optimize_webui=true
target_cpu="arm64"
use_allocator_shim=false
use_partition_alloc_as_malloc=false
v8_enable_sandbox=false

Some of these settings cannot be changed as they will make a successful CEF build impossible. Other settings can be changed but have untested consequences, e.g. is_component_build would allow building CEF not as a single "fat" framework but a set of separate dynamic libraries. but is not compatible with the way the obs-browser module is built for OBS Studio.

  1. Run the automate-git.py script

    3.1. Some command line arguments are mandatory and need to be provided by the user:

    • --download-dir specifies the directory to which the Chromium and CEF source trees will be checked out - after following step #1, ${PWD}/chromium_git can be used here, which will place the source trees in a subdirectory named "chromium_git"
    • --branch specifies the CEF branch name to build (see the table at the top of the document for possible values) - the value specified here simply needs to match a Git branch name available in the source repository
    • --arm64-build needs to be specified when building CEF for Apple Silicon-based Macs
    • --x64-build needs to be specified when building CEF for Intel-based Macs
    • --with-pgo-profiles needs to be specified to ensure that optimization profiles required by the Chromium build system are downloaded before the actual build

    3.2. These command line arguments are optional and customize the build:

    • --minimal-distrib configures the build system to create a minimal CEF binary distribution, containing just CEF and sources for the wrapper library
    • --client-distrib configures the build system to also create a client CEF binary distribution, containing a CEF test application
    • --minimal-distrib-only configures the build system to minimal CEF binary distribution only, ignoring other settings (see above)
    • --no-debug-build disables generation of Debug builds, the equivalent to adding is_debug=false to GN_DEFINES
    • --force-clean deletes the output directory and CEF distribution directory before configuring the build system

Additional build options can be checked by running automate-git.py --help. Different elements of a possible CEF build can be enabled or disabled to customise the exact configuration required.

  1. CEF will take several hours to checking out sources and build

Distribute

Once CEF has finished building, a package according to the specified build settings has been generated:

  • The generated binaries can be found in chromium_git/chromium/src/out - if available, the test applications can be found in that directory as well
  • The CEF distributable packages (minimal variants, as well as debug symbols, test clients, and full distribution with test program sources) can be found in chromium_git/chromoum/cef/binary_distrib

The distributable package contains the CEF framework as well as the sources for the CEF wrapper library. For OBS Studio, a pre-built CEF wrapper library needs to be added to the distributable package.

Generate the CEF Wrapper Library

  1. Ensure that CMake is installed on the build host - if CMake is not available, install it via Homebrew

  2. Either enter the directory of the distribution package or copy the contents to a new directory

  3. Configure the CEF wrapper build via CMake: cmake -S . -B build -G Xcode -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 -DUSE_SANDBOX=OFF

    • When building for Apple Silicon-based Macs, specify -DPROJECT_ARCH=arm64
    • When building for Intel-based Macs, specify -DPROJECT_ARCH=x86_64

  4. Build the CEF Wrapper in Debug configuration: cmake --build build --config Debug

  5. Build the CEF Wrapper in Release configuration: cmake --build build --config Release

  6. Clean up the build directory to only contain the created static wrapper libraries:

    • Remove all files and directories inside the build directory apart from the libcef_dll_wrapper directory
    • Inside the libcef_dll_wrapper directory, remove all files and directories apart from the Debug and Release directories

  7. Switch into the root content directory of the CEF distribution

  8. Generate the CEF distribution archive:

    • For Apple Silicon-based Macs, run tar -cvJf cef_binary_<BRANCH>_macos_arm64.tar.xz *. Replace <BRANCH> with the value used for automate-git.py before.
    • For Intel-based Macs, run tar -cvJf cef_binary_<BRANCH>_macos_x86_64.tar.xz *. Replace <BRANCH> with the value used for automate-git.py before.

Finalize

The generated .tar.xz archives can now be used to build OBS Studio by uploading them to a web host or CDN and changing the baseUrl for the cef dependency in OBS Studio's buildspec.json.

To update the associated hash values, simply run shasum -a 256 cef_binary_<BRANCH>_macos_<PLATFORM>.tar.xz to get the associated sha256 hash for the generated archives.

Clone this wiki locally