main 42e99a9

Go bindings for the Chromium Embedded Framework C API, using purego instead of cgo.

purego-cef

Go bindings for the Chromium Embedded Framework C API, using purego instead of cgo.

Linux only. CGO_ENABLED=0.

[!NOTE] purego-cef is usable today, but it is still pre-1.0. Expect API changes while the handwritten cef layer settles.

Status

purego-cef exposes the CEF C API through generated bindings and adds a smaller handwritten cef layer for the common paths.

What to expect today:

  • generated low-level bindings across the CEF C API
  • a smaller ergonomic cef layer for init, clients, and common handlers
  • shipped mocks for testing
  • ongoing API cleanup before 1.0

Architecture

The binding layer is generated from CEF C headers (~114 files). The generator parses all headers and produces:

  • Inbound port interfaces for every CEF handler and type
  • Outbound port interfaces grouping CEF free functions and object methods by domain
  • A composite CAPI interface embedding all outbound ports
  • Typed constructors for handlers and wrappers for CEF objects with automatic refcount management
  • C struct layouts and purego symbol registration
  • Doc comments extracted from CEF C headers

The public cef package then adds a small handwritten layer for the places where the raw C API is too awkward to expose directly.

A hand-written core domain handles UTF-16 string conversion, reference counting, CEF lifecycle orchestration, and the Bridge adapter implementing the CAPI interface.

Mocks for all interfaces are generated by Mockery v3 and shipped in cef/mocks/.

API shape

For most code, prefer the ergonomic handwritten layer when it exists:

  • cef.Settings instead of cef.RawSettings
  • cef.NewClient(...) with cef.Client
  • cef.NewLifeSpanHandler(...) with cef.LifeSpanHandler
  • cef.NewAudioHandler(...) with the decoded cef.AudioHandler interface
  • cef.ExecuteSubprocess() when you want subprocess status and errors without implicit os.Exit or stderr writes; cef.MaybeExitSubprocess() remains the short helper for main packages
  • cef.ExecuteSubprocessWithApp(app) when helper subprocess startup also needs a custom cef.App
  • cef.LifeSpanHandler popup callbacks receive a callback-scoped *cef.RawClientWriteSlot when CEF exposes a writable popup client out-param; check for nil before calling Set or Clear

Treat Raw* types as advanced escape hatches.

Usage

For main packages, cef.MaybeExitSubprocess() is the short path. If you need explicit subprocess status and error handling, use cef.ExecuteSubprocess() or cef.ExecuteSubprocessWithApp(app).

package main

import (
	"runtime"

	"github.com/bnema/purego-cef/cef"
)

func main() {
	runtime.LockOSThread()
	cef.MaybeExitSubprocess()

	if err := cef.Init(cef.DefaultSettings()); err != nil {
		panic(err)
	}
	defer cef.Shutdown()

	client := cef.NewClient(myClient{})
	_ = client

	// Your render loop here
	for {
		cef.DoMessageLoopWork()
	}
}

// Implement the user-facing client interface — only the methods you need.
type myClient struct{}

func (c myClient) GetLifeSpanHandler() cef.LifeSpanHandler { return nil }
func (c myClient) GetRenderHandler() cef.RenderHandler     { return myRenderer{} }
// ... other handler getters return nil

Requirements

  • Go 1.26+
  • CEF 150 runtime (the minimum accepted Chrome/CEF major; earlier versions are rejected at load time)

Runtime discovery

purego-cef locates libcef.so using this order:

  1. CEF_DIR environment variable
  2. Explicit Settings.CEFDir argument passed to cef.Init()
  3. /usr/lib/cef (the Arch Linux cef package install path), if libcef.so exists there
  4. ~/.local/share/cef

Arch Linux

sudo pacman -S cef

This installs /usr/lib/cef/libcef.so and the required Resources — no env var needed.

Runtime diagnostics

  • CEF_SKIP_VERSION_CHECK=1 bypasses the major-version guard only (diagnostics only; API 15000 hash validation always applies).

Building

CGO_ENABLED=0 go build ./...
CGO_ENABLED=0 go test ./...

Integration tests need the CEF runtime (adjust the directory as needed):

go test -tags=cef_integration ./integration

If your runtime is in a non-standard location, set CEF_DIR:

CEF_DIR=/custom/path go test -tags=cef_integration ./integration

Regenerating bindings

CEF_HEADERS=/usr/include/cef/include go generate ./...

Or manually:

go run ./cmd/cefgen \
  --headers-dir /usr/include/cef/include \
  --capi-dir internal/capi \
  --port-in-dir internal/ports/in \
  --port-out-dir internal/ports/out \
  --public-dir cef
mockery

Project layout

cef/                 public API (generated) + mocks
  bridge.go          hand-written: handler constructors, string helpers
  init.go            hand-written: Init(), Shutdown(), orchestration
internal/
  ports/in/          inbound port interfaces (generated)
  ports/out/         outbound port interfaces (generated) + composite CAPI (hand-written) + mocks
  core/              domain logic: engine, string marshaling, refcount (hand-written)
  capi/              purego bindings + bridge (generated + hand-written)
  loader/            dlopen libcef.so + version validation (hand-written)
cmd/cefgen/          binding generator (parser, model, emitter, templates)
integration/         integration tests (require CEF runtime)

License

MIT

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 30

↑↓ moveenter openesc close