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