Tim van der Lippe
27ff2f24ca
In the Chromium backend engineers can use `DCHECK()` to ensure certain invariants are held, but only execute these assertions in a debug build. [1] Release builds do not ship with DCHECKS enabled. In a similar fashion, introduce a build-time generated function `DHCECK` that is only generated when `devtools_dcheck_always_on` is set as GN arg. By default, `is_debug` builds enable `devtools_dcheck_always_on`. However, in a release build, you can explicitly set `devtools_dcheck_always_on` to `true` to achieve the same effect. When the GN arg is set, the build generates the `dcheck.js` file with an implementation that checks the condition and fails if it is not met. When the arg is not set, the function implementation remains empty and becomes a noop. To make sure that these functions calls are removed in a release build (rather than being a noop), the terser configuration is updated to treat these functions as pure. As such, terser will remove any calls if the function implementation is empty. In a release build that explicitly turns out the dchecks, terser will not remove the function calls. Lastly, to make sure that all code related to the dcheck is removed, the condition needs to be a lambda. If we were to make it a raw boolean, then `terser` would not be able to determine whether it can remove the condition itself and would leave that behind. In other words, the `DCHECK` call would still leave some artifacts behind, namely the condition computation itself. By making it a lambda, terser can deduce that the lambda creation has no side-effect and remove the lambda if the `DHCECK` call is removed. R=aerotwist@chromium.org [1]: https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++.md#check_dcheck_and-notreached Bug: none Change-Id: Ic396f102141d9eb67c8690bd2a601b56061b9d8c Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2894390 Auto-Submit: Tim van der Lippe <tvanderlippe@chromium.org> Reviewed-by: Paul Lewis <aerotwist@chromium.org> Reviewed-by: Jack Franklin <jacktfranklin@chromium.org> Commit-Queue: Tim van der Lippe <tvanderlippe@chromium.org> Commit-Queue: Jack Franklin <jacktfranklin@chromium.org>
DevTools build system templates
The DevTools build system contains several templates to integrate files in the build system. Below you can find an overview of which template/combination of templates you need to use and when.
Entrypoints and modules
The buildsystem has a concept of "entrypoints" and "modules".
An entrypoint is a file that exports all symbols that are considered the public API of that particular component.
For example, front_end/common/ exposes its public API in front_end/common/common.js.
Therefore, the common.js file is considered the entrypoint.
Rule: all entrypoints use the same name in their filename as the name of the folder.
All other files in a particular component are considered implementation details and therefore part of the "module".
Rule: an entrypoint only exports symbols that are considered the public API of that component. The public API includes functions/classes/etc... that are intended to be used by other modules
For example, for front_end/common/:
- The entrypoint is
front_end/common/common.ts - All other files such as
front_end/common/implementation_detail.tsare part of the "module"
devtools_entrypoint and devtools_module
The two templates devtools_entrypoint and devtools_module implement the respective roles of entrypoints/modules.
The devtools_entrypoint includes an entrypoint, which is the entrypoint filename.
The devtools_module contains a list of files that are considered the implementation of the component.
Example file for front_end/my_module/BUILD.gn:
import("../../scripts/build/ninja/devtools_entrypoint.gni")
import("../../scripts/build/ninja/devtools_module.gni")
devtools_module("my_module") {
sources = [
"implementation_detail.ts",
"some_other_file.ts",
]
deps = [
"../other_dependency:bundle",
]
}
devtools_entrypoint("bundle") {
entrypoint = "my_module.ts"
deps = [
":my_module",
]
}
Rule:
devtools_moduleis named the same name as the folder it resides in
Rule:
devtools_entrypointsis named "bundle", as in a release build it bundles with Rollup
Legacy: Non-TypeScript entrypoints
Not all modules are currently typechecked only by TypeScript. There are two other options, related to the legacy Closure Compiler.
Typescriptified modules (e.g. TypeScript + Closure Compiler)
Any module that is fully typescriptified (e.g. a JavaScript file that is typechecked by both TypeScript and Compiler Compiler) can be imported from both TypeScript modules and Closure Compile-checked modules.
Rule: Any typescriptified module can never contain an entrypoint or source file in their implementation that is TypeScript-authored. In practice this rule comes down to: you can only have a TypeScript-authored implementation file if the corresponding entrypoint is also TypeScript-authored.
As such, the following layout is used for TypeScriptified modules:
import("../../scripts/build/ninja/devtools_entrypoint.gni")
import("../../scripts/build/ninja/devtools_module.gni")
devtools_module("my_module") {
sources = [
"implementation_detail.js",
"some_other_file.js",
]
deps = [
"../other_dependency:bundle",
]
}
devtools_entrypoint("bundle") {
entrypoint = "my_module.js"
deps = [
":my_module",
]
}
Here, both the entrypoint and the sources of the module are all JavaScript files. All of these files are typechecked by Closure Compiler and TypeScript.
GRD file generation
To make sure that files are loaded in Chromium, DevTools generates a GRD file that includes all files that are allowed to be loaded by the backend. To generate the GRD, there are numerous variables that list all kinds of files.
Entrypoints
All entrypoints are listed in grd_files_release_sources specified in /config/gni/devtools_grd_files.gni.
Rule: in both release and debug builds, entrypoints are always included in the GRD file
Module implementation files
All implementation files for components are listed in grd_files_debug_sources specified in /config/gni/devtools_grd_files.gni.
Rule: the implementation files are only present in the GRD file in a debug build, because the release build bundles all files into the respective entrypoint