pdlgen generates Go code for the commands, events and types of the
Chrome DevTools Protocol. It is a core component of the
chromedp project. The generator follows the needs of chromedp.
Its aim is to produce
type safe, fast, efficient, idiomatic Go code that any Go program can
use to drive Chrome.
Every issue and every pull request for the cdproto package belongs in this
repository. None belongs in the cdproto repository, because cdproto is
generated output.
A workflow in this repository regenerates cdproto every day. When the
generated code changes, the workflow commits it and tags a release. See
Releases.
Install pdlgen in the usual Go way:
go install github.com/chromedp/pdlgen@latestpdlgen generates the github.com/chromedp/cdproto
package and a github.com/chromedp/cdproto/<domain> package for each domain. A
domain is a group of related commands, events and types, such as Page. The
--out option names the directory of a checkout of the cdproto
repository:
pdlgen --chromium=157.0.8084.3 --v8=15.7.23 --out=../cdprotoThe generator retrieves the protocol files from the Chromium source
tree and caches them. Then it replaces the contents of the
output directory. It keeps LICENSE, README.md, CHANGELOG.md, *.pdl,
go.mod, go.sum and any name that starts with a dot.
pdlgen --helpThe options are:
--chromiumis the Chromium version ofbrowser_protocol.pdl. Any Git tag or branch of the Chromium source tree works. The default is the latest version.--v8is the V8 version ofjs_protocol.pdl. The default is the version in theDEPSfile of the Chromium version.--latestuses the latest V8 version.--pdlreads one combined protocol file and retrieves nothing.--outor-ois the output directory.--cacheis the cache directory. The default ispdlgenin the user cache directory.--ttlis how long a cached file is used. The default is 24 hours, and0forces a new retrieval.--go-pkgis the Go package name of the output. The default isgithub.com/chromedp/cdproto.--go-wlis the comma-separated list of files that the cleaning step keeps. The default isLICENSE,README.md,CHANGELOG.md,*.pdl,go.mod,go.sum.--no-cleankeeps the files that the generator did not write.--debugwrites the files withoutgoimportsandgofmt.--versionor-vprints the version ofpdlgen, and--helpor-hprints the options.
The generator reads the protocol, skips what the protocol deprecates, and fills
standard Go text/template templates. Two rewrites change the
types. One removes name stuttering, so css.CSSStyle becomes css.Style. The
other gives each inline enum a named type. An inline enum is an enum that a
property or a parameter declares in place. For example, the type parameter of
Input.dispatchKeyEvent has the type input.DispatchKeyEventType.
Types that two domains need move to the cdp package, to prevent import
cycles. The cdp package also holds the typed API. Each command is a value of
the type cdp.Command with a parameter struct and a result struct. Each event
is a value of the type cdp.Event. docs/API.md
describes that API, and docs/GENERATOR.md describes every
step.
cdproto is tagged v0.<Chromium major>.<patch>, so the first release for
Chromium 157 is v0.157.0, and the next is v0.157.1. The Update workflow
makes the tags. v0.157.3 is the first release with the typed API. Each tag and
CHANGELOG.md in cdproto record the Chromium and V8 versions and the count of
API changes. The module stays at major version 0. Any release can contain an
incompatible change, because the protocol removes and renames things.
A new Chromium or V8 version alone makes no release. If the generated API is
the same, the workflow makes no commit and no tag. For this reason, the
Chromium version in version.go can be older than the newest Chromium build.
The package reports its versions with cdproto.ChromiumVersion() and
cdproto.V8Version(). docs/RELEASES.md has the rules.
The generated cdproto package builds with Go 1.25 and later. pdlgen, which
generates it, uses the current version of Go. Go 1.27 has encoding/json/v2 in
the standard library, but Go 1.25 and Go 1.26 have it only with
GOEXPERIMENT=jsonv2. To work without that setting, the subpackage
cdp/jsonv2 is the only generated package that imports a JSON package. It has
the names of the standard library, such as jsonv2.Value and
jsonv2.Unmarshal. On Go 1.27 or with GOEXPERIMENT=jsonv2, it uses the
standard packages. In all other cases it uses the module
github.com/go-json-experiment/json. The build tag cdproto_jsoncompat selects
the module on every version of Go, for tests. Use GOEXPERIMENT=nojsonv2 with
the tag on Go 1.27. See
the decision.
| Document | Contents |
|---|---|
AGENTS.md |
The rules for coding agents, which apply to a person too |
CONTRIBUTING.md |
How to change this repository |
docs/GENERATOR.md |
The pipeline, the templates and how to change them |
docs/RELEASES.md |
The workflows, the tags and the changelog |
docs/API.md |
The typed API that uses generics and iterators |
docs/PLAN.md |
Purpose, architecture, testing and open questions |
docs/BACKLOG.md |
Work that is known and not done |
docs/PROGRESS.md |
Where the work stands |
docs/decisions/ |
Every decision, one file each, named by date |