blob: 7304e8d36ac9ccce80a3e9fc7899bcd88de5747f [file] [log] [blame] [view]
Benedikt Meurer52d9f112024-10-18 09:21:071# Dependencies
2
3[TOC]
4
5## Managing dependencies
6
7If you need to manually roll a git dependency, it's not sufficient to update the
8revision in the DEPS file. Instead, use the gclient tool: `bash gclient setdep
9-r DEP@REV # for example build@afe0125ef9e10b400d9ec145aa18fca932369346` This
10will simultaneously update both the DEPS entry as well as the gitlink entry for
11the corresponding git submodule.
12
13To sync dependencies from Chromium to DevTools frontend, use
14`scripts/deps/roll_deps.py`. Note that this may: - Introduce unneeded
15whitespace/formatting changes. Presubmit scripts (e.g. invoked via `git cl
16upload`) will automatically fix these locally, so just apply the changes
17directly to your change (e.g. with `git commit --amend`) afterwards. - Introduce
18breaking changes to the devtools protocol, causing compilation failures.
19Unfortunately these need to be handled manually as there are some changes (e.g.
20removing an enum value) that cannot fail gracefully.
21
22The following scripts run as AutoRollers, but can be manually invoked if
23desired:
24
25- To roll the `HEAD` commit of DevTools frontend into Chromium, use
26 `scripts/deps/roll_to_chromium.py`.
27- To update DevTools frontend's DEPS, use `roll-dep`.
28
29## Third-party Guidelines
30
31When you want to integrate or use third-party content in DevTools, there are a
32couple of different ways to do so. Most of the time, we have to make a
33distinction between "third-party code we use as part of DevTools implementation"
34and "third-party code we use to build DevTools itself, but is not included in
35the product".
36
37### Third-party code included in DevTools bundle
38
39All third-party content that you want to ship as part of the DevTools bundle
40must be included in `front_end/third_party`. The typical way to update these
41packages is to download the relevant packages from [npm]. Since DevTools does
42not use a `package.json` to handle its dependencies (to make it possible to
43review third-party changes by legal), most packages bundles are fetched with
44`wget`.
45
46For all these packages, the [Chromium third-party guidelines] apply.
47
48Since DevTools ships as part of the Chrome binary, bundle size limitations
49apply. To make integration feasible, focus on small packages that (preferably)
50have no dependencies. This will make licensing checks feasible for Chromium
51reviewers and typically avoids inflating the bundle size.
52
53### Third-party tooling packages
54
55For all third-party packages that are used either as part of the DevTools build
56process or to augment engineers workflows (for example linters), we add them to
57`scripts/deps/manage_node_deps.py`. This Python script has been approved by
58Chromium licensing to be used, on the basis that it enforces all packages have a
59license that is compatible with a set of pre-defined licensees.
60
61If you want to use a new package as tooling process in engineer workflows, you
62can add the package to the `package.json` and run `npm run install-deps` to
63check in the new contents.
64
65Only add new license types to `LICENSES` after you received approval from
66`[email protected]`. Their response time is typically within 24
67hours, so this typically is not a big hurdle.
68
69To avoid excessive package updates, it is typically easiest to update all
70packages in `manage_node_deps.py` once a month. Since NPM packages can have a
71lot of (shared) transitive dependencies, updating the packages on a specific day
72increases the chances that shared dependencies are deduplicated and thus result
73in smaller repository sizes.
74
75> **WARNING:** Updating tools such as Rollup and TypeScript will cause all build
76> cache output to be purged, as they are part of all DevTools modules. Whenever
77> you are updating either of these tools, update these at the end of a working
78> day to avoid full rebuilds for other engineers.
79
80### Chromium third-party DEPS
81
82Some packages related to infrastructure are maintained by Chromium infra teams.
83These packages are typically uploaded to cloud storage buckets or are explicitly
84mirrored to a repository on https://chromium.googlesource.com. Examples include
85[GN][] (Chromium/DevTools build system) or [clang-format][] (multi-language
86formatter).
87
88The packages in `DEPS` are typically kept automatically up-to-date with
89autorollers. These autorollers will periodically update packages, which
90engineers can fetch with running `gclient sync`.
91
92These `DEPS` are checked out on all bots, which includes Chromium and
93DevTools-specific bots. To avoid excessive network bandwidth usage, by default
94do not check out packages if they are only used in specific situations.
95
96Only include packages that are maintained by Chromium infrastructure teams and
97are used to build DevTools in `DEPS`. For packages that are DevTools-specific,
98prefer adding them to `scripts/deps/manage_node_deps.py` instead.
99
100[npm]: https://www.npmjs.com/
101[Chromium third-party guidelines]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/adding_to_third_party.md
102[GN]: https://gn.googlesource.com/gn/+/master/docs/reference.md
103[clang-format]: https://clang.llvm.org/docs/ClangFormat.html