Skip to content

Latest commit

 

History

History
86 lines (58 loc) · 4.12 KB

README.md

File metadata and controls

86 lines (58 loc) · 4.12 KB
Raw

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.

General guidance

Whenever you are implementing a template, take into account that GN expects the source folder structure to be mirrored in the out-directory. Historically, DevTools used the location-agnostic out/Default/resources/inspector folder, but we have since adopted the GN guidelines for mirroring our source folder. Primary motivations are the instability of the separate folder, as well as required hacks to compute "relative" sub-folders in GN. Since GN has no notion of a "root" folder for DevTools, computation of sub-folders can only be done based on heuristics, which will fail sooner rather than later.

Additionally, GN is a timestamp-based build system when checking for correctness. This means that you want to avoid writing to the file system if the content stays the same. For Node scripts, use the writeIfChanged function from write-if-changed.js to integrate nicely with GN.

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/:

  1. The entrypoint is front_end/common/common.ts
  2. All other files such as front_end/common/implementation_detail.ts are 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_module is named the same name as the folder it resides in

Rule: devtools_entrypoints is named "bundle", as in a release build it bundles with Rollup

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