This document describes a high-level architecture of Blink's top-level directories.
core/ and modules/ are directories to implement web platform features defined in the specs. IDL files and their implementations should go to core/ and modules/.
Note that the specs do not have a notion of “core” and “modules”. The distinction between core/ and modules/ is for implementational convenience to avoid putting everything in core/ (which decreases code modularity and increases build time). Basically web platform features that are tighly coupled with HTML, CSS and other fundamental parts of DOM should go to core/. Other web platform features should go to modules/.
In terms of dependencies, modules/ can depend on core/. core/ cannot depend on modules/. modules/xxx/ can depend on modules/yyy/.
bindings/ is a directory to put files that heavily use V8 APIs.
In terms of dependencies, bindings/core/ and core/ are in the same link unit. The only difference is how heavily they are using V8 APIs. If a given file is using a lot of V8 APIs, it should go to bindings/core/. Otherwise, it should go to core/. (The same principle applies to bindings/modules/ and modules/.)
The rationale for this split is: V8 APIs are complex, error-prone and security-sensitive, so we want to put V8 API usages in one directory.
platform/ is a directory to implement low-level libraries of Blink. For example, platform/scheduler/ implements a task scheduler for all tasks posted by Blink. To avoid putting everything in core/ and modules/, consider factoring out low-level functionalities to platform/.
platform/wtf/ is a directory to implement Blink-specific containers (e.g., Vector, HashTable, String).
In terms of dependencies, core/ and modules/ can depend on platform/. platform/ cannot depend on core/ and modules/.
controller/ is a directory to implement high-level functionalities on top of core/ and modules/. Functionalities that use or drive Blink should go to controller/.
In terms of dependencies, controller/ can depend on core/ and modules/. core/ and modules/ cannot depend on controller/.
devtools/ implements a client-side of the Chrome DevTools, including all JS & CSS to run the DevTools webapp.
In terms of dependencies, devtools/ is a stand-alone directory.
build/ contains scripts to build Blink.
In terms of dependencies, build/ is a stand-alone directory.
Dependencies only flow in the following order:
See this diagram.
devtools/ and build/ are stand-alone directories.
core/, modules/, bindings/, platform/ and controller/ can use std:: types and types defined in Chromium. The philosophy is that we should share as much code between Chromium and Blink as possible.
However, there are a couple of types that really need to be optimized for Blink's workload (e.g., Vector, HashTable, Bind, AtomicString). These types are defined in platform/wtf/. If there is an equivalent in platform/wtf/, Blink must use the type in platform/wtf/ instead of the type defined in Chromium. For example, Blink should not use std::vector (except places where a conversion between std::vector and WTF::Vector is needed).
To prevent use of random types, we control allowed types by whitelisting them in DEPS and a presubmit script.
core/, modules/, bindings/, platform/ and controller/ can use Mojo and directly talk with the browser process. This allows removal of unnecessary public APIs and abstraction layers and it is highly recommended.
If you have any questions about the directory architecture and dependencies, reach out to firstname.lastname@example.org!